APIs¶

Create API metadata¶

POST /apis

Code samples

curl -X POST https://localhost:9543/api/v0.9/apis \
  -u {username}:{password} \
  -H 'Content-Type: multipart/form-data' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Creates Developer Portal API metadata from either a full API artifact ZIP, an API metadata YAML file (api.yaml / devportal.yaml / mcp.yaml), or a metadata JSON string. An API definition file is required unless supplied by the artifact ZIP. The YAML spec block accepts: displayName, version, description, type, status, agentVisibility, tags, labels, referenceId, endpoints (sandboxUrl, productionUrl), businessInformation (owners), and subscriptionPlans. The service also stores labels, subscription plan mappings, image metadata, and schema definitions for GraphQL APIs when provided. Via the JSON metadata field, type is required — an omitted type is rejected with 400 (via YAML, an omitted spec.type defaults to REST). MCP servers must be created via POST /api/v0.9/mcp-servers instead — a request whose resolved type is MCP is rejected with 400. subscriptionPlans links existing org-level plans to this API by name — it does not create plans. In YAML it is a string array (["Gold", "Silver"]). In the JSON metadata field it is an object array where only id is used ([{"id":"Gold"}]); extra fields such as planId, displayName, or requestCount are ignored.

Payload

definition: string
artifact: string
metadata: '{"name":"Weather API","version":"v1","description":"Weather forecast
  API","type":"REST","agentVisibility":"VISIBLE",
  "status":"PUBLISHED","tags":["weather"],"labels":["default"],"endPoints":{
  "productionURL":"https://api.example.com/weather",
  "sandboxURL":"https://sandbox.example.com/weather"},"subscriptionPlans":[{"id":"Gold"}]}'

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	object	true	API metadata upload. Send either `artifact`, or `metadata` with `definition`. For a GraphQL API the `definition` field carries the SDL schema. (MCP servers are created via `/mcp-servers` with the dedicated `McpServerMultipartBody`, not this body.)
» definition	body	string(binary)	false	API definition file. For REST/SOAP/etc. this is the OpenAPI/WSDL/AsyncAPI contract; for a GraphQL API it is the SDL schema.
» artifact	body	string(binary)	false	Full API ZIP artifact containing metadata and definition files.
» metadata	body	string	false	API metadata, supplied either as a JSON string field or as an uploaded YAML/JSON file (a k8s-style document with `kind`, `metadata.name`, and a `spec` block; file names `metadata.yaml`/`.yml`/`.json`, or the legacy `api.yaml`/`mcp.yaml`/`devportal.yaml`). As a JSON string it accepts these top-level fields: `name`, `version`, `description`, `type`, `agentVisibility`, `status`, `referenceId`, `id`, `tags`, `labels`, `owners`, `endPoints` (productionURL, sandboxURL), and `subscriptionPlans` (array of `{ id }` objects — only `id` is read; the plan must already exist in the organization). `id` becomes the API's stored handle; when the API is created from a YAML artifact instead, the handle is always taken from `metadata.name`.

Example responses

201 Response

{
  "id": "weather-api-v1",
  "refId": "cp-api-12345",
  "name": "Weather API",
  "title": "Weather Forecast API",
  "version": "v1",
  "status": "PUBLISHED",
  "description": "Weather forecast API.",
  "type": "REST",
  "agentVisibility": "VISIBLE",
  "tags": [
    "weather"
  ],
  "labels": [
    "default"
  ],
  "endPoints": {
    "productionURL": "https://api.example.com/weather",
    "sandboxURL": "https://sandbox.example.com/weather"
  },
  "subscriptionPlans": [
    {
      "id": "Gold"
    }
  ]
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
201	Created	Created API metadata payload returned by the service.	ApiMetadataCreateResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Response Headers¶

Status	Header	Type	Format	Description
201	Location	string	uri	URL of the created API metadata resource.

List API metadata¶

GET /apis

Code samples

curl -X GET https://localhost:9543/api/v0.9/apis \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Lists API metadata for an organization. The service supports exact filters by API name, version, and tags, free-text search with query, and view filtering. Unknown query parameters are rejected. MCP-typed records are never returned here — use GET /api/v0.9/mcp-servers.

Authentication¶

Parameters

Name	In	Type	Required	Description
query	query	string	false	Free-text API metadata search term.
name	query	string	false	Exact API name filter.
version	query	string	false	Exact API version filter.
tags	query	string	false	Comma-separated tag names. Matches APIs tagged with any of the given names.
view	query	string	false	Developer Portal view name used to filter visible APIs.
limit	query	integer	false	Maximum number of records to return.
offset	query	integer	false	Number of records to skip before returning results.

Example responses

200 Response

{
  "list": [
    {
      "id": "weather-api-v1",
      "refId": "cp-api-12345",
      "name": "Weather API",
      "version": "v1",
      "status": "PUBLISHED",
      "description": "Weather forecast API.",
      "type": "REST",
      "agentVisibility": "VISIBLE",
      "labels": [
        "default"
      ],
      "endPoints": {
        "sandboxURL": "https://sandbox.example.com/weather",
        "productionURL": "https://api.example.com/weather"
      }
    }
  ],
  "count": 1,
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	List of API metadata DTOs.	Inline
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[allOf]	false	none	none

allOf

Name	Type	Required	Restrictions	Description
»» anonymous	ApiInfoResponse	false	none	Fields are returned at the root of ApiMetadataResponse / ApiMetadataCreateResponse (not nested under an `apiInfo` key) — this schema exists only to share the field set between the two via `allOf`.
»»» name	string	false	none	none
»»» title	string¦null	false	none	none
»»» remotes	[object]	false	none	none
»»» version	string	false	none	none
»»» status	string	false	none	API lifecycle status.
»»» description	string	false	none	none
»»» type	string	false	none	The stored/returned type constant (src/utils/constants.js API_TYPE) — distinct from the request-time keyword accepted on create/update (see `type` in ApiMetadataMultipartBody: REST, SOAP, MCP, WS, WEBSUB, GRAPHQL). REST maps to `RestApi` and WEBSUB maps to `WebSubApi`; the rest are returned unchanged.
»»» referenceId	string¦null	false	none	External reference ID. Present when the API was created from a `devportal.yaml` artifact whose `spec` block sets `referenceId` — the create response echoes the parsed YAML back.
»»» agentVisibility	string	false	none	none
»»» addedLabels	[string]	false	none	none
»»» removedLabels	[string]	false	none	none
»»» owners	ApiOwnersResponse	false	none	none
»»»» technicalOwner	string	false	none	none
»»»» businessOwner	string	false	none	none
»»»» businessOwnerEmail	string	false	none	none
»»»» technicalOwnerEmail	string	false	none	none
»»» apiImageMetadata	ApiImageMetadataResponse	false	none	none
»»»» additionalProperties	string	false	none	none
»»» tags	[string]	false	none	none
»»» labels	[string]	false	none	none

and

Name	Type	Required	Restrictions	Description
»» anonymous	object	false	none	none
»»» id	string	false	none	The API's handle (unique per org). Not the internal database uuid.
»»» refId	string¦null	false	none	Platform API (Control Plane) reference ID for this API. Used for MCP registry visibility filtering and included in outbound webhook event payloads. Null/absent for APIs that exist only in the Developer Portal and are not registered with the Platform API — e.g. MCP servers published via the registry.
»»» dataSource	string¦null	false	none	Indicates which content matched the search term: `METADATA` if the match was in the API's own metadata, or a content type (e.g. a value from the API Content `type` field) if the match was inside an uploaded content file. Only computed by getAllApiMetadataForOrganization when both the `query` search parameter is supplied and the database is PostgreSQL — absent on SQLite (the dev default) and absent from every other operation (get/create/update single API).
»»» planId	string	false	none	none
»»» endPoints	ApiEndpointsResponse	false	none	none
»»»» sandboxURL	string	false	none	none
»»»» productionURL	string	false	none	none
»»» subscriptionPlans	[SubscriptionPlanResponse]	false	none	none
»»»» id	string	false	none	The plan's handle (unique per org). Not the internal database uuid.
»»»» displayName	string	false	none	none
»»»» description	string	false	none	none
»»»» limits	[object]	false	none	Rate/quota limits enforced for this plan. Empty when the plan is unlimited.
»»»»» limitType	string	false	none	none
»»»»» limitCount	any	false	none	Returned as a string when the stored count exceeds the safe integer range, otherwise a number. Unlimited plans have no limit entries — the `limits` array is empty.

oneOf

Name	Type	Required	Restrictions	Description
»»»»»» anonymous	integer	false	none	none

xor

Name	Type	Required	Restrictions	Description
»»»»»» anonymous	string	false	none	none

continued

Name	Type	Required	Restrictions	Description
»»»»» timeUnit	string¦null	false	none	none
»»»»» timeAmount	integer	false	none	none
»»»» refId	string¦null	false	none	Platform API subscription plan UUID associated with this plan.
»»»» orgId	string	false	none	none
»»»» createdBy	string	false	none	Identity of the user who created this subscription plan, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses and list items.
»»»» updatedBy	string	false	none	Identity of the user who last updated this subscription plan, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses only, omitted on list items.
»»»» createdAt	string(date-time)	false	none	none
»»»» updatedAt	string(date-time)	false	none	none
»»» createdBy	string	false	none	Identity of the user who created this API, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses and list items.
»»» updatedBy	string	false	none	Identity of the user who last updated this API, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses only, omitted on list items.
»»» createdAt	string(date-time)	false	none	none
»»» updatedAt	string(date-time)	false	none	none
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Enumerated Values

Property	Value
status	PUBLISHED
status	DEPRECATED
type	RestApi
type	SOAP
type	Mcp
type	WS
type	WebSubApi
type	GRAPHQL
agentVisibility	VISIBLE
agentVisibility	HIDDEN
limitType	REQUEST_COUNT
limitType	EVENT_COUNT
limitType	BANDWIDTH
limitType	TOTAL_TOKEN_COUNT
timeUnit	MINUTE
timeUnit	HOUR
timeUnit	DAY
timeUnit	MONTH
timeUnit	null

Enumerated Values

Property	Value
status	error

Get API metadata¶

GET /apis/{apiId}

Code samples

curl -X GET https://localhost:9543/api/v0.9/apis/{apiId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Retrieves a single API metadata record by Developer Portal API ID.

Authentication¶

Parameters

Name	In	Type	Required	Description
apiId	path	string	true	The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.

Example responses

200 Response

{
  "id": "weather-api-v1",
  "refId": "cp-api-12345",
  "name": "Weather API",
  "title": "Weather Forecast API",
  "remotes": [],
  "version": "v1",
  "status": "PUBLISHED",
  "description": "Weather forecast API.",
  "type": "REST",
  "agentVisibility": "VISIBLE",
  "labels": [
    "default"
  ],
  "endPoints": {
    "sandboxURL": "https://sandbox.example.com/weather",
    "productionURL": "https://api.example.com/weather"
  },
  "subscriptionPlans": [
    {
      "id": "Gold"
    }
  ],
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2026-05-07T08:30:00Z",
  "updatedAt": "2026-05-07T08:30:00Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

"string"

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	API metadata DTO returned by the service.	ApiMetadataResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Plain text success response.	string
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Update API metadata¶

PUT /apis/{apiId}

Code samples

curl -X PUT https://localhost:9543/api/v0.9/apis/{apiId} \
  -u {username}:{password} \
  -H 'Content-Type: multipart/form-data' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Updates Developer Portal API metadata and its stored definition. Accepts the same YAML spec fields and metadata JSON format as the create operation. The update flow can also adjust label mappings, subscription plan mappings, schema definitions, and image metadata. Status changes to unpublished are rejected when active subscriptions exist. type is required (see the create operation) and is immutable — it must match the API's existing type; a different value is rejected with 409.

Payload

definition: string
artifact: string
metadata: '{"name":"Weather API","version":"v1","description":"Weather forecast
  API","type":"REST","agentVisibility":"VISIBLE",
  "status":"PUBLISHED","tags":["weather"],"labels":["default"],"endPoints":{
  "productionURL":"https://api.example.com/weather",
  "sandboxURL":"https://sandbox.example.com/weather"},"subscriptionPlans":[{"id":"Gold"}]}'

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	object	true	API metadata upload. Send either `artifact`, or `metadata` with `definition`. For a GraphQL API the `definition` field carries the SDL schema. (MCP servers are created via `/mcp-servers` with the dedicated `McpServerMultipartBody`, not this body.)
» definition	body	string(binary)	false	API definition file. For REST/SOAP/etc. this is the OpenAPI/WSDL/AsyncAPI contract; for a GraphQL API it is the SDL schema.
» artifact	body	string(binary)	false	Full API ZIP artifact containing metadata and definition files.
» metadata	body	string	false	API metadata, supplied either as a JSON string field or as an uploaded YAML/JSON file (a k8s-style document with `kind`, `metadata.name`, and a `spec` block; file names `metadata.yaml`/`.yml`/`.json`, or the legacy `api.yaml`/`mcp.yaml`/`devportal.yaml`). As a JSON string it accepts these top-level fields: `name`, `version`, `description`, `type`, `agentVisibility`, `status`, `referenceId`, `id`, `tags`, `labels`, `owners`, `endPoints` (productionURL, sandboxURL), and `subscriptionPlans` (array of `{ id }` objects — only `id` is read; the plan must already exist in the organization). `id` becomes the API's stored handle; when the API is created from a YAML artifact instead, the handle is always taken from `metadata.name`.
apiId	path	string	true	The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.

Example responses

200 Response

{
  "id": "weather-api-v1",
  "refId": "cp-api-12345",
  "name": "Weather API",
  "title": "Weather Forecast API",
  "remotes": [],
  "version": "v1",
  "status": "PUBLISHED",
  "description": "Weather forecast API.",
  "type": "REST",
  "agentVisibility": "VISIBLE",
  "labels": [
    "default"
  ],
  "endPoints": {
    "sandboxURL": "https://sandbox.example.com/weather",
    "productionURL": "https://api.example.com/weather"
  },
  "subscriptionPlans": [
    {
      "id": "Gold"
    }
  ],
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2026-05-07T08:30:00Z",
  "updatedAt": "2026-05-07T08:30:00Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	API metadata DTO returned by the service.	ApiMetadataResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Delete API metadata¶

DELETE /apis/{apiId}

Code samples

curl -X DELETE https://localhost:9543/api/v0.9/apis/{apiId} \
  -u {username}:{password} \
  -H 'Accept: text/plain' \
  -H 'Authorization: Bearer {access-token}'

Deletes API metadata when the API has no active subscriptions.

Authentication¶

Parameters

Name	In	Type	Required	Description
apiId	path	string	true	The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.

Example responses

200 Response

"string"

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Plain text success response.	string
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error