---
title: capability_request
description: Ask for a provider or job the catalog does not cover yet, same as POST /v1/capability-requests.
---

<WorksIn />

Request a provider or job the catalog does not cover yet, the same as
`POST /v1/capability-requests`. Use it after [`search`](/mcp-tools/search) or [`search_catalog`](/mcp-tools/search-catalog) comes back empty with a
[`no_supply_for_job`](/errors/job-refusals#no_supply_for_job) warning, to tell the team what is missing. `title` and `description` are
yours to write; `desiredInputs`/`desiredOutputs` are optional field lists the endpoint should
take or return.

## Inputs

| Argument | Type | Required | Default | Limits | Meaning |
| --- | --- | --- | --- | --- | --- |
| `title` | string | Yes | - | 1-200 chars | Short name for the request. |
| `description` | string | Yes | - | 1-2000 chars | What the job should do. |
| `desiredInputs` | string[] | No | - | up to 100 items, each 1-200 chars | Field names the endpoint should accept. |
| `desiredOutputs` | string[] | No | - | up to 100 items, each 1-200 chars | Field names the endpoint should return. |
| [`idempotencyKey`](/concepts/idempotency) | string | Yes | - | 1-300 chars | Stable per request; a retry with the same key is a no-op, never a duplicate ask. |

## Example call

```json
{
  "title": "Verify a UK company registration number",
  "description": "Look up a company by its Companies House number and confirm it is active.",
  "desiredInputs": ["companyNumber"],
  "desiredOutputs": ["status", "registeredName"],
  "idempotencyKey": "capreq-2026-09-28-uk-companies-house"
}
```

## Example answer

```json
{
  "requestId": "3040f05a-118b-4d45-a442-02d4b3e089cc",
  "title": "Verify a UK company registration number",
  "description": "Look up a company by its Companies House number and confirm it is active.",
  "desiredInputs": ["companyNumber"],
  "desiredOutputs": ["status", "registeredName"],
  "status": "open",
  "createdAt": "2026-09-28T10:00:00.000Z"
}
```

## Errors

A missing or wrong-typed field returns [`validation_error`](/errors/rest-errors#validation_error) naming it, for example
`Invalid input: expected string, received undefined at idempotencyKey`. `title` and `description`
over their length limits are refused the same way. Reusing an `idempotencyKey` with a different
`title`/`description` fails as [`idempotency_conflict`](/errors/rest-errors#idempotency_conflict), the same rule [`run`](/mcp-tools/run) follows.

## REST and CLI

- REST: [`POST /v1/capability-requests`](/reference/requests/post-v1-capability-requests)

<Related />