Generated HTTP reference for the 4 operations the published OpenAPI document describes under providers.

Providers

This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET `/v1/providers`

List the MCP servers this project can attach to a session

Query parameters

Name	Type	Required	Description
`category`	`string`	no	—
`country`	`string`	no	—
`q`	`string`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request — the body or query did not match the schema.

Response 200

Field	Type	Required	Description
`filtered`	`integer`	yes	—
`servers`	array of ServerCatalogRow	yes	—
`total`	`integer`	yes	—

Example response

{
  "total": 0,
  "filtered": 0,
  "servers": [
    {
      "id": "servercatalogrow_0000000000000000",
      "name": "Example",
      "pkg": "string",
      "category": "string",
      "country": "string",
      "auth_type": "string",
      "tools_count": 1,
      "status": "string",
      "sandbox_available": true,
      "subaccount_provisionable": true,
      "engine_provisionable": true,
      "engine_status": "none"
    }
  ]
}

Example request

curl -X GET https://api.codespar.dev/v1/providers \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/providers/{slug}`

Read one provider

Responses

Status	Body	Description
`200`	ServerCatalogRow	OK
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`auth_type`	`string`	yes	—
`category`	`string`	yes	—
`country`	`string`	yes	—
`description`	`string,null`	yes	—
`engine_provisionable`	`boolean`	yes	Has an engine provisioning descriptor AND is not quarantined.
`engine_status`	`"none"` \| `"available"` \| `"quarantined"`	yes	Carries the reason `engine_provisionable` is false.
`id`	`string`	yes	—
`name`	`string`	yes	—
`pkg`	`string`	yes	—
`provider_docs_url`	`string,null`	no	—
`provider_homepage`	`string,null`	no	—
`provider_logo_fallback_url`	`string,null`	no	—
`provider_logo_url`	`string,null`	no	—
`sandbox_available`	`boolean`	no	—
`sandbox_url`	`string,null`	no	—
`status`	`string`	yes	—
`subaccount_provisionable`	`boolean`	yes	—
`tools_count`	`integer`	yes	—

Example response

{
  "id": "servercatalogrow_0000000000000000",
  "name": "Example",
  "pkg": "string",
  "category": "string",
  "country": "string",
  "auth_type": "string",
  "tools_count": 1,
  "status": "string",
  "sandbox_available": true,
  "subaccount_provisionable": true,
  "engine_provisionable": true,
  "engine_status": "none"
}

Example request

curl -X GET https://api.codespar.dev/v1/providers/{slug} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/providers/{slug}/auth-schema`

The connect form for one provider

Path parameters

Name	Type	Required	Description
`slug`	`string`	yes	The provider slug, which is also the catalog primary key.

Responses

Status	Body	Description
`200`	object	OK
`404`	object	Not Found — no such provider for this caller. A generated provider belonging to another project answers here too, identically to one that does not exist: the listing already hides it, so answering differently would leak what the listing conceals.

Response 200

Field	Type	Required	Description
`auth_type`	`"api_key"` \| `"path_secret"` \| `"oauth"` \| `"cert"` \| `"none"` \| `"hmac_signed"` \| `"jwt_ecdsa"` \| `"two_header"` \| `"cdp"`	yes	The provider's declared auth mechanism, taken straight from the column. Nine values, which is the column constraint's set and NOT the six the shared types package publishes: three of these nine are wire values the published schema would reject, so validate against this list rather than against a generated type of that field.
`base_url`	`string`	yes	The provider host for this environment, or an empty string when the catalog holds no endpoint row for it.
`environment`	`"live"` \| `"test"`	yes	The environment the credential authenticates in. Not a parameter of the request.
`fields`	array of object	yes	In the order the form should render them.
`oauth_authorize_url`	`string,null`	yes	Where an OAuth connect lands the operator. Null for every other mechanism.
`server_id`	`string`	yes	Echo of the slug. The catalog primary key IS the slug — there is no second id.

Example response

{
  "server_id": "srv_0000000000000000",
  "auth_type": "api_key",
  "environment": "live",
  "base_url": "https://example.com/hook",
  "fields": [
    {
      "name": "Example",
      "kind": "api_key",
      "label": "Example",
      "header_name": "Example"
    }
  ]
}

Example request

curl -X GET https://api.codespar.dev/v1/providers/{slug}/auth-schema \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

POST `/v1/providers/{slug}/verify-connection`

Test one provider connection's credential

Path parameters

Name	Type	Required	Description
`slug`	`string`	yes	The provider slug, which is also the catalog primary key.

Responses

Status	Body	Description
`200`	object	OK. The credential authenticated at the provider. `latency_ms` is the probe's own round trip.
`401`	object	The PROVIDER rejected the stored credential — a verdict, and the only failure here that is one. `detail` carries the provider's own words. This 401 never describes the caller's own credential: one that does not authenticate is refused before the handler runs.
`404`	object \| object	Not Found, and this status carries TWO different bodies. A generated provider belonging to another project is refused before the check runs, with the bare `\{ error, server_id \}` shape and no `ok` key. A provider that has a verify recipe but no catalog row reaches the checker and comes back as an ordinary failure with `ok: false` and `error: "server_unknown"`. Branch on `ok`, not on the status.
`409`	object	`redirect_not_followed`. The configured host answered with a redirect, which the probe does not follow, so the credential was never judged. Retrying cannot resolve it and reconfiguring can — which is why it is not a 502.
`424`	object	`not_connected`. There is no usable credential to test: no active connection for this project and provider, or the vault returned nothing for the reference it holds. This body carries the extra `hint` / `alternative` steer.
`501`	object	`verify_unsupported`. Nothing ships that can check this provider — no recipe and no declared probe. The first real call will report authentication errors directly.
`502`	object	`provider_unreachable`, and it is WIDER than its name. It is returned for a transport failure or timeout, and also for EVERY provider response that is not 2xx, 3xx, 401 or 403 — a provider 400 or 404 arrives here too. Read `status` before retrying: absent means nothing was reached and a retry is reasonable; a 4xx there means the provider answered and will answer the same way again.
`503`	object	`endpoint_missing`. The provider is known but its catalog entry cannot be called as configured. An operator fixes this; a caller cannot.

Response 200

Field	Type	Required	Description
`account`	object	no	Absent when the check ran through the generic probe rather than a provider-specific recipe: only a recipe extracts an account summary. Its absence is not a weaker pass.
`latency_ms`	`integer`	yes	—
`ok`	`true`	yes	—
`provider`	`string`	yes	—

Example response

{
  "ok": true,
  "provider": "string",
  "account": {
    "id": "obj_0000000000000000",
    "name": "Example",
    "extras": {}
  },
  "latency_ms": 0
}

Example request

curl -X POST https://api.codespar.dev/v1/providers/{slug}/verify-connection \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

Providers

Providers

GET /v1/providers

GET /v1/providers/{slug}

GET /v1/providers/{slug}/auth-schema

POST /v1/providers/{slug}/verify-connection

On this page

GET `/v1/providers`

GET `/v1/providers/{slug}`

GET `/v1/providers/{slug}/auth-schema`

POST `/v1/providers/{slug}/verify-connection`