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

Servers

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.

The Servers API lets you browse CodeSpar's catalog of MCP servers. Each server represents an integration with a commerce provider -- a payment gateway, shipping carrier, fiscal authority, messaging platform, banking API, ERP system, or crypto exchange.

Use the Servers API to understand what integrations are available, discover capabilities before creating sessions, and build dynamic UIs that show users which providers they can connect.

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

All endpoints require authentication via Bearer token. See Authentication.

GET /v1/servers

Returns the server catalog with filtering and search capabilities. Results are paginated.

Auth required: Yes (scope: servers:read)

Query parameters

Parameter	Type	Default	Description
`category`	`string`	--	Filter by category: `payments`, `fiscal`, `logistics`, `messaging`, `banking`, `erp`, `crypto`
`country`	`string`	--	Filter by country code (ISO 3166-1 alpha-2): `BR`, `MX`, `AR`, `CO`, `CL`
`q`	`string`	--	Full-text search across server name, description, and capabilities
`status`	`string`	--	Filter by status: `stable`, `beta`, `alpha`, `deprecated`
`auth_type`	`string`	--	Filter by auth type: `api_key`, `path_secret`, `oauth`, `cert`, `hmac_signed`, `none`
`limit`	`number`	`50`	Results per page (max 100)
`offset`	`number`	`0`	Pagination offset

Response schema

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "category": "string",
      "countries": ["string"],
      "capabilities": ["string"],
      "auth_type": "string",
      "status": "string",
      "tools_count": "number",
      "icon_url": "string"
    }
  ],
  "total": "number",
  "limit": "number",
  "offset": "number"
}

Example: list all servers

curl "https://api.codespar.dev/v1/servers" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- 200 OK:

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "description": "Global payment processing platform. Supports cards, Pix, boleto, and 135+ currencies.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["checkout", "subscriptions", "refunds", "pix", "boleto", "cards"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 12,
      "icon_url": "https://codespar.dev/icons/stripe.svg"
    },
    {
      "id": "mercadopago",
      "name": "Mercado Pago",
      "description": "Latin America's leading payment platform. Native Pix, boleto, and Mercado Credito.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["pix", "boleto", "checkout", "wallet", "installments"],
      "auth_type": "oauth",
      "status": "stable",
      "tools_count": 15,
      "icon_url": "https://codespar.dev/icons/mercadopago.svg"
    }
  ],
  "total": 114,
  "limit": 50,
  "offset": 0
}

Example: filter by category

Retrieve only payment servers:

curl "https://api.codespar.dev/v1/servers?category=payments" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- 200 OK:

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "description": "Global payment processing platform. Supports cards, Pix, boleto, and 135+ currencies.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["checkout", "subscriptions", "refunds", "pix", "boleto", "cards"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 12,
      "icon_url": "https://codespar.dev/icons/stripe.svg"
    },
    {
      "id": "asaas",
      "name": "Asaas",
      "description": "Brazilian payment platform specializing in Pix, boleto, and recurring billing.",
      "category": "payments",
      "countries": ["BR"],
      "capabilities": ["pix", "boleto", "subscriptions", "split_payments"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 10,
      "icon_url": "https://codespar.dev/icons/asaas.svg"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Example: filter by country

Retrieve servers available in Mexico:

curl "https://api.codespar.dev/v1/servers?country=MX" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- 200 OK:

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "description": "Global payment processing platform. Supports cards, Pix, boleto, and 135+ currencies.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["checkout", "subscriptions", "refunds", "pix", "boleto", "cards"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 12,
      "icon_url": "https://codespar.dev/icons/stripe.svg"
    },
    {
      "id": "conekta",
      "name": "Conekta",
      "description": "Mexican payment platform. Native SPEI, OXXO cash payments, and card processing.",
      "category": "payments",
      "countries": ["MX"],
      "capabilities": ["spei", "oxxo", "cards", "checkout"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 8,
      "icon_url": "https://codespar.dev/icons/conekta.svg"
    },
    {
      "id": "cfdi",
      "name": "CFDI",
      "description": "Mexican fiscal document generation (Comprobante Fiscal Digital por Internet) via SAT.",
      "category": "fiscal",
      "countries": ["MX"],
      "capabilities": ["cfdi_ingreso", "cfdi_egreso", "cfdi_traslado", "cancelation"],
      "auth_type": "cert",
      "status": "stable",
      "tools_count": 6,
      "icon_url": "https://codespar.dev/icons/cfdi.svg"
    }
  ],
  "total": 18,
  "limit": 50,
  "offset": 0
}

Example: full-text search

Search for servers that support Pix:

curl "https://api.codespar.dev/v1/servers?q=pix" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- 200 OK:

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "description": "Global payment processing platform. Supports cards, Pix, boleto, and 135+ currencies.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["checkout", "subscriptions", "refunds", "pix", "boleto", "cards"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 12,
      "icon_url": "https://codespar.dev/icons/stripe.svg"
    },
    {
      "id": "mercadopago",
      "name": "Mercado Pago",
      "description": "Latin America's leading payment platform. Native Pix, boleto, and Mercado Credito.",
      "category": "payments",
      "countries": ["BR", "MX", "AR", "CO", "CL"],
      "capabilities": ["pix", "boleto", "checkout", "wallet", "installments"],
      "auth_type": "oauth",
      "status": "stable",
      "tools_count": 15,
      "icon_url": "https://codespar.dev/icons/mercadopago.svg"
    },
    {
      "id": "asaas",
      "name": "Asaas",
      "description": "Brazilian payment platform specializing in Pix, boleto, and recurring billing.",
      "category": "payments",
      "countries": ["BR"],
      "capabilities": ["pix", "boleto", "subscriptions", "split_payments"],
      "auth_type": "api_key",
      "status": "stable",
      "tools_count": 10,
      "icon_url": "https://codespar.dev/icons/asaas.svg"
    }
  ],
  "total": 5,
  "limit": 50,
  "offset": 0
}

Example: combine filters

Retrieve stable payment servers in Brazil:

curl "https://api.codespar.dev/v1/servers?category=payments&country=BR&status=stable" \
  -H "Authorization: Bearer csk_live_abc123..."

GET /v1/servers/:id/tools

Returns a server's tool list with input schemas. (There is no standalone GET /v1/servers/:id: server metadata comes from the list endpoint's rows; this endpoint serves the tools; GET /v1/servers/:id/auth-schema serves the credential shape the connect flow needs.)

Auth required: Yes (scope: servers:read)

curl example

curl https://api.codespar.dev/v1/servers/stripe/tools \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK`

{
  "tools": [
    {
      "name": "stripe_create_checkout_session",
      "description": "Create a Stripe Checkout session with a payment link",
      "input_schema": {
        "type": "object",
        "properties": {
          "line_items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "price_data": {
                  "type": "object",
                  "properties": {
                    "currency": { "type": "string" },
                    "product_data": {
                      "type": "object",
                      "properties": {
                        "name": { "type": "string" }
                      }
                    },
                    "unit_amount": { "type": "number" }
                  }
                },
                "quantity": { "type": "number" }
              }
            }
          },
          "mode": {
            "type": "string",
            "enum": ["payment", "subscription", "setup"]
          },
          "success_url": { "type": "string" },
          "cancel_url": { "type": "string" }
        },
        "required": ["line_items", "mode"]
      }
    },
    {
      "name": "stripe_create_refund",
      "description": "Refund a Stripe payment",
      "input_schema": {
        "type": "object",
        "properties": {
          "payment_intent": { "type": "string", "description": "ID of the PaymentIntent to refund" },
          "amount": { "type": "number", "description": "Amount to refund in cents (partial refund). Omit for full refund." },
          "reason": { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] }
        },
        "required": ["payment_intent"]
      }
    }
  ]
}

Server-specific tools (like stripe_create_checkout_session) are only available in sessions that connect to that server. The 15 meta-tools are always available regardless of which servers are connected.

Server categories

Category	Examples
`payments`	Stripe, Mercado Pago, Asaas, PagSeguro, Pagarme, Conekta, Inter, Sicredi
`fiscal`	NF-e, NFS-e, SPED, CT-e, MDFe, CFDI
`logistics`	Correios, Jadlog, Loggi, Mercado Envios, Total Express, DHL, Estafeta
`messaging`	Twilio, WhatsApp Business, SendGrid, Mailgun, Amazon SNS
`banking`	Inter, Itau, Bradesco, Banco do Brasil, Sicoob, Nubank
`erp`	Bling, Tiny, Omie, TOTVS, ContaAzul, Nuvemshop
`crypto`	Mercado Bitcoin, Foxbit, Binance Pay, Coinbase Commerce

Per-category counts change as the catalog grows; query GET /v1/servers?category=<name> for live numbers.

Server status values

Status	Description	Recommendation
`stable`	Production-ready, fully tested, SLA-backed	Safe for production use
`beta`	Functional but may have breaking changes in minor versions	Safe for staging; pin the server version in production
`alpha`	Experimental, limited support, may be removed	Development and testing only
`deprecated`	Scheduled for removal; an alternative is available	Migrate to the suggested replacement

Authentication types

Each server requires one of these authentication methods, configured in the Auth Configs section of the dashboard:

Auth type	Description	Examples
`api_key`	Authenticate with a secret key from the provider	Stripe, Asaas, SendGrid
`path_secret`	Secrets embedded in URL path plus optional companion header	Z-API, Take Blip, Evolution API
`oauth`	OAuth 2.0 flow for user-level access	Mercado Pago, Melhor Envio
`cert`	mTLS with X.509 client certificate (PEM)	Banco do Brasil, Itaú, Bradesco, Santander, Caixa, Sicoob, Sicredi, C6, Original
`hmac_signed`	Per-request HMAC signature over `timestamp + method + path + body`	Foxbit
`jwt_ecdsa`	Per-request ES256 JWT signed with an ECDSA P-256 private key	Coinbase Developer Platform
`two_header`	Two co-equal credential headers, no Authorization Bearer	Cielo, Transbank, Kushki, Payway
`none`	No credentials required	Brasil API

Rate limits

The catalog reads on this page (GET /v1/servers, /v1/servers/:id/tools, /v1/servers/:id/auth-schema) carry no rate limit of their own. The limiter that exists applies to tool execution, and it is not tiered by plan.

It is a token bucket keyed by (account, server) — so the budget is per upstream provider, not per API key and not per plan. The default bucket is a capacity of 60 with 1 token/second of refill; a few providers that publish generous ceilings get more (Stripe 300 / 25 per second, Asaas 120 / 10 per second). Buckets are held in the API process, so a multi-replica deployment gives each replica its own.

Exceeding it answers 429 with a Retry-After header in seconds and retry_after_ms in the body:

{
  "error": "rate_limited",
  "server": "asaas",
  "retry_after_ms": 1400,
  "message": "Rate limit reached for server \"asaas\". Retry in ~2s."
}

There are no X-RateLimit-Limit / -Remaining / -Reset headers. Read Retry-After and back off with jitter.

Rate limits are not billing — see Billing for the pricing model.

Error responses

Status	Error code	Description
`400`	`invalid_query`	Invalid query parameter value
`401`	`unauthorized`	Invalid or missing API key
`403`	`forbidden`	The key does not hold the `servers:read` scope
`404`	`not_found`	Server ID does not exist in the catalog

429 rate_limited does not appear on these three endpoints — it belongs to tool execution, on POST /v1/sessions/:id/tool-calls.

Next steps

REFERENCE

Sessions API

Create sessions against these servers and execute tool calls.

CONCEPT

Tools & Meta-Tools

How the 15 meta-tools route to specific servers by domain.

CONCEPT

Authentication

Configure provider credentials in the dashboard auth vault.

GLOSSARY

Glossary

Definitions for MCP, server, provider, BACR, and more.

Every operation, from the spec

Generated from the published OpenAPI document, so it never drifts from what the API actually serves. The section above is written by hand and carries what a schema cannot: the object model, field rules, and the order to call things in.

GET `/v1/servers`

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/servers \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/servers/{id}/auth-schema`

Read the credential form a provider needs, without reading any credential

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The provider id, which is also the catalog row's primary key.

Responses

Status	Body	Description
`200`	object	OK
`404`	object	The provider is not visible to this project. Not the `apiError` envelope and not `\{ error: "not_found" \}`: a third shape, built at the route.

Response 200

Field	Type	Required	Description
`auth_type`	`string`	yes	LEFT OPEN ON PURPOSE, and the reason is measured rather than cautious. The column admits nine values today — `api_key`, `path_secret`, `oauth`, `cert`, `none`, `hmac_signed`, `jwt_ecdsa`, `two_header`, `cdp` — under a CHECK constraint that has been widened four times (migrations 0064, 0066, 0074, 0091, over the six of 0026). The handler casts the column straight into this field, so the set of values a client can receive is the DB's, not any narrower published enum. Closing this to six would describe a wire that already carries more.
`base_url`	`string`	yes	The host a call to this provider will be sent to, in the caller's environment. Empty string when the provider has no endpoint row.
`environment`	`"live"` \| `"test"`	yes	Taken from the calling credential, and what `base_url` was resolved against.
`fields`	array of object	yes	In the order the form should render, which is the catalog's declared order: the visible field before the masked one for the multi-field types.
`oauth_authorize_url`	`string,null`	yes	Where the browser leg starts, environment-resolved the same way. Null for every auth type other than `oauth`, and also null for an `oauth` provider with no configuration row.
`server_id`	`string`	yes	—

Example response

{
  "server_id": "srv_0000000000000000",
  "auth_type": "string",
  "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/servers/{id}/auth-schema \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/servers/{id}/tools`

List the tools a provider exposes

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The provider id.

Responses

Status	Body	Description
`200`	object	OK
`404`	object	The provider is not visible to this project. Not the `apiError` envelope and not `\{ error: "not_found" \}`: a third shape, built at the route.

Response 200

Field	Type	Required	Description
`server_id`	`string`	yes	Echoes the id from the path, whether or not it named anything.
`tools`	array of object	yes	—
`total`	`integer`	yes	Always equal to the length of `tools`.

Example response

{
  "server_id": "srv_0000000000000000",
  "total": 0,
  "tools": [
    {
      "name": "Example"
    }
  ]
}

Example request

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

POST `/v1/servers/{id}/verify-connection`

Ask the provider whether this project's stored credential still works

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The provider id.

Responses

Status	Body	Description
`200`	object	OK
`401`	object	`provider_rejected`. The provider answered 401 or 403: it looked at the credential and said no. Retrying unchanged will fail the same way.
`404`	object \| object	Two shapes under one status. The route's own gate answers `\{ error, server_id \}` before any work happens; the credential resolver answers the verify outcome's `server_unknown` when the provider is absent from the catalog. Parse the union.
`409`	object	`redirect_not_followed`. The configured host answered 3xx. The probe is issued with redirects disabled on purpose, so the credential was never judged by anyone: this is the absence of a verdict, not a negative one. Retrying cannot change it; the host or the catalog entry has to.
`424`	object	`not_connected`. There is nothing to verify: either no active connection exists for this project and provider, or one exists and its stored credential did not resolve to a value. Connect the provider, or reconnect it.
`501`	object	`verify_unsupported`. This provider ships neither a bespoke recipe nor a declared probe, so there is no safe read to issue. Nothing is wrong with the credential and nothing about it has been learned; the first real call is where authentication errors will surface.
`502`	object	`provider_unreachable`. EVERY non-2xx that is not a redirect and not a 401 or 403 lands here, together with network failures and the per-call timeout (10 seconds by default, deployment-configurable). That includes a provider's 400, 404, 409, 422 and 429. Only some of those are worth retrying, and `status` is the field that separates them.
`503`	object	`endpoint_missing`. The provider is in the catalog but the row that says where to reach it is missing or contradicts how the connection was stored. A catalog or connection problem on our side, not a verdict on the credential and not a provider outage.

Response 200

Field	Type	Required	Description
`account`	object	no	ABSENT on the probe path, and absent on the recipe path whenever the recipe found nothing it recognised in the response. Present means the read reached a real account; absent does NOT mean it did not.
`latency_ms`	`integer`	yes	Wall-clock milliseconds around the outbound call.
`ok`	`true`	yes	—
`provider`	`string`	yes	The provider id from the path.

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/servers/{id}/verify-connection \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

Servers

On this page