---
title: "APIs"
description: "Create, list, get, update, and delete API metadata via the API Portal REST API."
canonical_url: https://wso2.com/api-platform/docs/api-portal/1.0.0/rest-api/apis/
md_url: https://wso2.com/api-platform/docs/api-portal/1.0.0/rest-api/apis.md
tags:
  - cloud
  - api-portal
  - rest-api
author: WSO2 API Platform Documentation Team
last_updated: 2026-07-24
content_type: "reference"
---

# APIs

## Create API metadata

<a id="opIdcreateApiMetadata"></a>

`POST /apis`

> Code samples

```shell

curl -X POST https://localhost:9543/api-portal/api/v0.9/apis \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json' \
  -F 'definition=@definition.yaml' \
  -F 'artifact=@artifact.zip' \
  -F '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"}]}'

```

Creates API metadata from either a full API artifact ZIP, an API metadata YAML file (`api.yaml` / `metadata.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-portal/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.

### Authentication

<aside class="warning">
This operation requires a <strong>Bearer JWT</strong> access token in the <code>Authorization</code> header.

Required scopes (the token must carry at least one of): `dp:api:create`, `dp:api:manage`

</aside>

<h3 id="create-api-metadata-parameters">Parameters</h3>

|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. Supply it in either of two forms:|

#### Detailed descriptions

**» metadata**: API metadata. Supply it in either of two forms:

- A JSON string field.
- An uploaded YAML or JSON file — a Kubernetes-style document with `kind`,
  `metadata.name`, and a `spec` block. Accepted file names are
  `metadata.yaml`, `.yml`, `.json`, `api.yaml`, or `mcp.yaml`.

As a JSON string, these top-level fields are read: `name`, `version`,
`description`, `type`, `agentVisibility`, `status`, `referenceId`, `id`, `tags`,
`labels`, `owners`, `endPoints` (`productionURL`, `sandboxURL`), and
`subscriptionPlans`.

`subscriptionPlans` is an array of `{ id }` objects. Only `id` is read, and the
plan must already exist in the organization.

The stored handle comes from `id`. When the API is created from a YAML artifact
instead, the handle always comes from `metadata.name`.

> Example responses
>
> 201 Response

```json
{
  "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.

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

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

> 404 Response

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

> 409 Response

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

> 500 Response

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

<h3 id="create-api-metadata-responses">Responses</h3>

|Status|Meaning|Description|Schema|
|---|---|---|---|
|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|Created API metadata payload returned by the service.|[ApiMetadataCreateResponse](schemas.md#schemaapimetadatacreateresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|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](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Resource not found.|[ErrorResponse](schemas.md#schemaerrorresponse)|
|409|[Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)|The request conflicts with an existing resource.|[ErrorResponse](schemas.md#schemaerrorresponse)|
|500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error.|[ErrorResponse](schemas.md#schemaerrorresponse)|

<h3 id="create-api-metadata-responseschema">Response schema</h3>

#### 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

<a id="opIdgetAllApiMetadataForOrganization"></a>

`GET /apis`

> Code samples

```shell

curl -X GET https://localhost:9543/api-portal/api/v0.9/apis \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

```

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-portal/api/v0.9/mcp-servers`.

### Authentication

<aside class="warning">
This operation requires a <strong>Bearer JWT</strong> access token in the <code>Authorization</code> header.

Required scopes (the token must carry at least one of): `dp:api:read`, `dp:api:manage`

</aside>

<h3 id="list-api-metadata-parameters">Parameters</h3>

|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|API 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

```json
{
  "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.

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

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

> 500 Response

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

<h3 id="list-api-metadata-responses">Responses</h3>

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|List of API metadata DTOs.|Inline|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|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](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error.|[ErrorResponse](schemas.md#schemaerrorresponse)|

<h3 id="list-api-metadata-responseschema">Response schema</h3>

Status Code **200**

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

*allOf*

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[ApiInfoResponse](schemas.md#schemaapiinforesponse)|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 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](schemas.md#schemaapiownersresponse)|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](schemas.md#schemaapiimagemetadataresponse)|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 API 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](schemas.md#schemaapiendpointsresponse)|false|none|none|
|»»»» sandboxURL|string|false|none|none|
|»»»» productionURL|string|false|none|none|
|»»» subscriptionPlans|[[SubscriptionPlanResponse](schemas.md#schemasubscriptionplanresponse)]|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](schemas.md#schemapagination)|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

<a id="opIdgetApiMetadata"></a>

`GET /apis/{apiId}`

> Code samples

```shell

curl -X GET https://localhost:9543/api-portal/api/v0.9/apis/{apiId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

```

Retrieves a single API metadata record by API ID.

### Authentication

<aside class="warning">
This operation requires a <strong>Bearer JWT</strong> access token in the <code>Authorization</code> header.

Required scopes (the token must carry at least one of): `dp:api:read`, `dp:api:manage`

</aside>

<h3 id="get-api-metadata-parameters">Parameters</h3>

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

> Example responses
>
> 200 Response

```json
{
  "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": "alice@example.com",
  "updatedBy": "alice@example.com",
  "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.

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

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

> 404 Response

```
"string"
```

> 500 Response

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

<h3 id="get-api-metadata-responses">Responses</h3>

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|API metadata DTO returned by the service.|[ApiMetadataResponse](schemas.md#schemaapimetadataresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|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](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Plain text success response.|string|
|500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error.|[ErrorResponse](schemas.md#schemaerrorresponse)|

<h3 id="get-api-metadata-responseschema">Response schema</h3>

#### Enumerated Values

|Property|Value|
|---|---|
|status|error|

## Update API metadata

<a id="opIdupdateApiMetadata"></a>

`PUT /apis/{apiId}`

> Code samples

```shell

curl -X PUT https://localhost:9543/api-portal/api/v0.9/apis/{apiId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json' \
  -F 'definition=@definition.yaml' \
  -F 'artifact=@artifact.zip' \
  -F '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"}]}'

```

Updates 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`.

### Authentication

<aside class="warning">
This operation requires a <strong>Bearer JWT</strong> access token in the <code>Authorization</code> header.

Required scopes (the token must carry at least one of): `dp:api:update`, `dp:api:manage`

</aside>

<h3 id="update-api-metadata-parameters">Parameters</h3>

|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. Supply it in either of two forms:|
|apiId|path|string|true|The API's handle (unique per org). Resolves only to REST, SOAP, WebSocket, WebSub, and GraphQL APIs. Model Context Protocol (MCP) servers are addressed via `/mcp-servers`.|

#### Detailed descriptions

**» metadata**: API metadata. Supply it in either of two forms:

- A JSON string field.
- An uploaded YAML or JSON file — a Kubernetes-style document with `kind`,
  `metadata.name`, and a `spec` block. Accepted file names are
  `metadata.yaml`, `.yml`, `.json`, `api.yaml`, or `mcp.yaml`.

As a JSON string, these top-level fields are read: `name`, `version`,
`description`, `type`, `agentVisibility`, `status`, `referenceId`, `id`, `tags`,
`labels`, `owners`, `endPoints` (`productionURL`, `sandboxURL`), and
`subscriptionPlans`.

`subscriptionPlans` is an array of `{ id }` objects. Only `id` is read, and the
plan must already exist in the organization.

The stored handle comes from `id`. When the API is created from a YAML artifact
instead, the handle always comes from `metadata.name`.

> Example responses
>
> 200 Response

```json
{
  "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": "alice@example.com",
  "updatedBy": "alice@example.com",
  "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.

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

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

> 404 Response

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

> 409 Response

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

> 500 Response

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

<h3 id="update-api-metadata-responses">Responses</h3>

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|API metadata DTO returned by the service.|[ApiMetadataResponse](schemas.md#schemaapimetadataresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|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](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Resource not found.|[ErrorResponse](schemas.md#schemaerrorresponse)|
|409|[Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)|The request conflicts with an existing resource.|[ErrorResponse](schemas.md#schemaerrorresponse)|
|500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error.|[ErrorResponse](schemas.md#schemaerrorresponse)|

<h3 id="update-api-metadata-responseschema">Response schema</h3>

#### Enumerated Values

|Property|Value|
|---|---|
|status|error|

## Delete API metadata

<a id="opIddeleteApiMetadata"></a>

`DELETE /apis/{apiId}`

> Code samples

```shell

curl -X DELETE https://localhost:9543/api-portal/api/v0.9/apis/{apiId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: text/plain'

```

Deletes API metadata when the API has no active subscriptions.

### Authentication

<aside class="warning">
This operation requires a <strong>Bearer JWT</strong> access token in the <code>Authorization</code> header.

Required scopes (the token must carry at least one of): `dp:api:delete`, `dp:api:manage`

</aside>

<h3 id="delete-api-metadata-parameters">Parameters</h3>

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|apiId|path|string|true|The API's handle (unique per org). Resolves only to REST, SOAP, WebSocket, WebSub, and GraphQL APIs. Model Context Protocol (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.

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

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

> 404 Response

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

> 409 Response

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

> 500 Response

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

<h3 id="delete-api-metadata-responses">Responses</h3>

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Plain text success response.|string|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|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](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Resource not found.|[ErrorResponse](schemas.md#schemaerrorresponse)|
|409|[Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)|The request conflicts with an existing resource.|[ErrorResponse](schemas.md#schemaerrorresponse)|
|500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error.|[ErrorResponse](schemas.md#schemaerrorresponse)|

<h3 id="delete-api-metadata-responseschema">Response schema</h3>

#### Enumerated Values

|Property|Value|
|---|---|
|status|error|