# Context4 documentation

Public product and technical documentation. Relative links resolve against https://ctx4.me. Examples are not evidence of successful execution; never disclose credentials in chat.

## Deployment addresses

- Documentation: https://ctx4.me/docs.md
- Agent index: https://ctx4.me/docs/agent-index.json
- Console and connections: https://console.ctx4.me/integrations
- MCP: https://ctx4.me/mcp
- HTTP API: https://ctx4.me/v1
- Composio base URL: https://ctx4.me/compat/context4/v1
- OpenAPI: https://ctx4.me/docs/openapi.json
- HTTP/MCP inventory: https://ctx4.me/docs/api-index.json
- Composio routes: https://ctx4.me/docs/compat-routes.json
- Connectors: https://ctx4.me/docs/connectors.json

# Agent setup

Source: https://ctx4.me/docs/agent-setup

## MCP

- Server: `https://ctx4.me/mcp`.
- Transport: Streamable HTTP.
- Human sign-in: browser OAuth, without issuing a Context4 API key.
- [Resource discovery](https://ctx4.me/.well-known/oauth-protected-resource/mcp), [OAuth discovery](https://ctx4.me/.well-known/oauth-authorization-server).
- [Console and accounts](https://console.ctx4.me/integrations).

Start with this page. Open other material for the step you are working on. Documentation and an MCP configuration entry do not prove access to data.

## 1. Identify the client

Identify the application from reliable environment context, not the model. If unknown, ask once: ChatGPT, Claude, Codex, Claude Code, Hermes, OpenClaw, or another MCP client?

Cloud clients cannot reach localhost documentation or a local MCP server. Stop and explain the need for a reachable HTTPS deployment. Do not invent a domain or silently substitute the production server.

## 2. Skills and client configuration

Check existing Context4 skills and tools. Reuse a suitable MCP connection. Do not overwrite another configuration or edited files without consent.

For normal operation, install `context4` and `context4-setup`; add `context4-workflows` for tasks across systems. [File manifest and SHA-256](https://ctx4.me/docs/skills-index.json), [package descriptions](https://ctx4.me/docs/skills.md). Read the whole package before saving it, including references. If the client cannot persist skills, use this guidance in the current chat and state that there is no persistent installation.

Open only the pair of links for your client:

| Client | Connection | Skills |
| --- | --- | --- |
| ChatGPT | [Plugin](https://ctx4.me/docs/connect-chatgpt.md) | [Installation](https://ctx4.me/docs/skills-chatgpt.md) |
| Claude web/desktop | [Remote connector](https://ctx4.me/docs/connect-claude.md) | [ZIP upload](https://ctx4.me/docs/skills-claude.md) |
| Codex | [Direct MCP](https://ctx4.me/docs/connect-codex.md) | [Files](https://ctx4.me/docs/skills-codex.md) |
| Claude Code | [HTTP MCP](https://ctx4.me/docs/connect-claude-code.md) | [Files](https://ctx4.me/docs/skills-claude-code.md) |
| Hermes | [MCP/OAuth](https://ctx4.me/docs/connect-hermes.md) | [Installation](https://ctx4.me/docs/skills-hermes.md) |
| OpenClaw | [MCP/OAuth](https://ctx4.me/docs/connect-openclaw.md) | [Installation](https://ctx4.me/docs/skills-openclaw.md) |

If the chat cannot change client settings, show exact manual steps. The user confirms sign-in, workspace, and consent. Wait for MCP tools to appear; explain a restart or new chat if needed. Installing a skill does not create an OAuth grant.

## Other MCP clients

For an unlisted client, use its native remote Streamable HTTP MCP configuration with the address above and OAuth discovery. Check skill storage against the actual client's documentation; a standard package contains SKILL.md and references. Do not guess configuration paths or CLI flags. If persistent skills are unsupported, use the guidance for this conversation and state the limitation explicitly.

## 3. Core tools

The global `/mcp` endpoint provides five meta-tools. Use the actual client's schemas; see the [full reference](https://ctx4.me/docs/mcp-tools.md).

| Tool | Purpose |
| --- | --- |
| `CONTEXT4_SEARCH_TOOLS` | Find an action for a service and task |
| `CONTEXT4_GET_TOOL_SCHEMAS` | Get exact arguments for discovered actions |
| `CONTEXT4_MANAGE_CONNECTIONS` | Inspect accounts or obtain a Connect Link |
| `CONTEXT4_WAIT_FOR_CONNECTIONS` | Wait for an account to become ready |
| `CONTEXT4_MULTI_EXECUTE_TOOL` | Execute the task with verified arguments |

Do not guess tool slugs or use another product's tools. COMPOSIO aliases are permitted only in a session that actually lists them.

## 4. Connect a business account

If the task or service is unknown, ask. Discover a suitable read, fetch its schema, and inspect connections. Ask the user to choose when multiple accounts are available. If authorization is needed, obtain a link through `CONTEXT4_MANAGE_CONNECTIONS`, show it to the user, and wait for actual readiness through `CONTEXT4_WAIT_FOR_CONNECTIONS`, respecting retry hints. Do not construct an authorization URL manually or request secrets in chat.

## 5. Confirm readiness with a read

Perform one permitted read through `CONTEXT4_MULTI_EXECUTE_TOOL`. Inspect every result. A successful empty response means the query works but has no matching data. Pending status, an error, a discovered schema, or a displayed link does not yet prove readiness. If no read is available, explain the limitation; do not create a record as a test.

Briefly report the connected service/account, what was checked, and a useful next task. Writes, deletions, and messages must stay within the user's instruction.

## As needed

[Providers](https://ctx4.me/docs/agent-providers.md), [errors and MCP](https://ctx4.me/docs/ai-mcp.md), [connections](https://ctx4.me/docs/connections.md), [revoking access](https://ctx4.me/docs/access-and-disconnect.md), [all chapters](https://ctx4.me/docs.md). For server integrations: [API](https://ctx4.me/docs/api-reference.md), [SDK/proxy](https://ctx4.me/docs/composio-sdk.md). Do not load the full API reference for ordinary MCP setup.

For a person: [open the HTML instructions](https://ctx4.me/docs/agent-setup).

## Data and terms

Context4 is free. Operation content is proxied without persistent storage. Account and authorization data is processed separately. [Data handling](https://ctx4.me/docs/data-handling.md) · [Privacy](https://ctx4.me/privacy) · [Terms](https://ctx4.me/terms) · [Support and deletion](https://ctx4.me/support#delete).

---

# What is Context4

Source: https://ctx4.me/docs/product-overview

Context4 is a service that connects CRMs and other work apps to AI through MCP (Model Context Protocol). It helps teams and developers find work data and perform available actions from an AI client or their own application.

Context4 connects AI and applications to external services through managed connections. Account authorization is stored by the platform; an agent receives available actions and their schemas, selects an account and completes the task within your permissions.

## Three ways to work

| Task | Interface | Start here |
| --- | --- | --- |
| Give AI tasks | Remote MCP with browser sign-in | [Quickstart](https://ctx4.me/docs/quickstart.md) |
| Embed actions in an application | Public HTTP API and compatible Composio SDK | [Technical documentation](https://ctx4.me/docs/api-reference.md) |
| Receive object changes and exports | Source syncs | [Data and sync](https://ctx4.me/docs/syncs.md) |

## What the platform provides

- Account connections, multiple accounts for one service and managed sharing.
- Tool search, input and output schemas, and execution subject to policies and quotas.
- Execution records, states and attempts for checking results.
- A catalog of provider HTTP methods and calls through a connected account.
- Syncs, entity schemas and historical exports available for each source.

Availability is determined by the live catalog, connection state and permissions. A service page in the [catalog](https://ctx4.me/apps) helps you choose an integration; executable tools are discovered after connection. Context4 does not promise every service's entire API, identical schemas or identical sync modes.

## From task to result

Describe the desired result and account. The agent finds a suitable action, retrieves its schema, checks the connection and sends arguments. After execution, it checks the state and actual data. Explicitly authorize changes, deletions and sending messages: tool access by itself does not authorize arbitrary actions.

Read more: [concepts](https://ctx4.me/docs/core-concepts.md), [connections](https://ctx4.me/docs/connections.md), [access and disconnection](https://ctx4.me/docs/access-and-disconnect.md), [workflows](https://ctx4.me/docs/business-cases.md).

## Why AI needs your work context

Without access to work data, AI can explain how to manage sales, but it does not know which deals you have open. Context means data from selected accounts: customers, tasks and other available records. Tools let AI move from discussion to an action in a service when the connection has the required permissions.

For example, the [amoCRM MCP connector](https://ctx4.me/apps/amocrm) supports examining available deals and contacts, while the [Bitrix24 connector](https://ctx4.me/apps/bitrix24) supports working with its CRM and tasks. Each service page describes support for individual actions; final availability is checked in your account.

## Start without building an integration

Choose [ChatGPT](https://ctx4.me/connect/chatgpt) or [Claude Code](https://ctx4.me/connect/claude) in the connection guides. Copy the prompt, set up the client and personally approve access to your work service. Start by reading data, then authorize changes you are ready to verify.

MCP is the protocol through which an AI client calls external tools. Context4 provides that access to work services; it does not replace your AI or CRM. [How MCP and tools work](https://ctx4.me/docs/ai-mcp.md).

## How to connect a CRM to ChatGPT or Claude

First connect Context4 to your AI using the [ChatGPT](https://ctx4.me/docs/connect-chatgpt.md) or [Claude](https://ctx4.me/docs/connect-claude.md) guide. Then select a CRM in the [service catalog](https://ctx4.me/apps) and authorize the account you want to use. A catalog page does not replace connecting the account and checking permissions.

## What AI can do with your work data

Available actions depend on the connector, connected account and permissions. Before changing a deal, task or another object, check the action and approve it in your AI client. Read [how to verify execution](https://ctx4.me/docs/actions.md) and [how to revoke access](https://ctx4.me/docs/access-and-disconnect.md).

---

# Context4 skills

Source: https://ctx4.me/docs/skills

## Ready-to-use skills

For normal setup, install `context4` and `context4-setup`. Add the third package for tasks across systems.

| Skill | Purpose | Files | Archive |
| --- | --- | --- | --- |
| `context4` | Services, tools, accounts, and results | [SKILL.md](https://ctx4.me/skills/context4/SKILL.md) | [ZIP](https://ctx4.me/skills/context4/archive.zip) |
| `context4-setup` | Client, MCP/plugin, sign-in, and the first read | [SKILL.md](https://ctx4.me/skills/context4-setup/SKILL.md) | [ZIP](https://ctx4.me/skills/context4-setup/archive.zip) |
| `context4-workflows` | Data and tasks across several systems | [SKILL.md](https://ctx4.me/skills/context4-workflows/SKILL.md) | [ZIP](https://ctx4.me/skills/context4-workflows/archive.zip) |

Archives contain SKILL.md, references, license, and attribution. The [file manifest and SHA-256](https://ctx4.me/docs/skills-index.json) let an agent save the package file by file. MCP and links are bound to the current deployment.

## Installation

[ChatGPT](https://ctx4.me/docs/skills-chatgpt.md), [Claude](https://ctx4.me/docs/skills-claude.md), [Codex](https://ctx4.me/docs/skills-codex.md), [Claude Code](https://ctx4.me/docs/skills-claude-code.md), [Hermes](https://ctx4.me/docs/skills-hermes.md), [OpenClaw](https://ctx4.me/docs/skills-openclaw.md).

Give the agent the [universal instructions](https://ctx4.me/docs/agent-setup.md) and ask it to install the skills. It will identify the client, read the files, and save complete packages. Existing edited skills are compared first rather than overwritten.

## Skills and MCP

A skill provides the workflow. MCP provides tools, OAuth grants permissions, and a provider connection supplies the account. Saving a file does not authorize a service. If the client cannot persist skills, the guide can be used in the current chat, but this is not a persistent installation.

## Composio foundation

The router is adapted from the [official Composio skill](https://github.com/ComposioHQ/composio/tree/231122de19abd820eac91549382e407e2d2cbe06/skills/composio), MIT. The unchanged original, license, and hashes are retained separately in the source. Working packages replace tools, addresses, and authorization with actual Context4 equivalents. Composio CLI is not installed. Playbooks inside Composio search are a different mechanism that we do not claim to have implemented in Context4.

---

# Providers: agent guidance

Source: https://ctx4.me/docs/agent-providers

## From task to action

The [service catalog](https://ctx4.me/apps) and [JSON catalog](https://ctx4.me/docs/connectors.json) are reference information. Permitted actions come from current MCP discovery, not from the existence of a website page.

1. Take the service and task from the user's instruction. Do not connect every system in advance.
2. Discover actions through `CONTEXT4_SEARCH_TOOLS` and fetch schemas through `CONTEXT4_GET_TOOL_SCHEMAS`.
3. Check the account and permissions. Ask when the choice is ambiguous; for sign-in, obtain a real Connect Link and wait for readiness.
4. Use returned fields and IDs. A CRM contact ID is not a recipient ID in another service.

## Service specifics

- [amoCRM](https://ctx4.me/apps/amocrm): deals, contacts, and tasks through discovered actions and their schemas.
- [Bitrix24](https://ctx4.me/apps/bitrix24): separate portal permissions; do not copy arguments from amoCRM.
- [Wazzup](https://ctx4.me/apps/wazzup): recipient/channel from the schema; send only on the user's instruction.
- Telephony, finance, and other services: the [catalog](https://ctx4.me/apps) and JSON above. Implementation does not mean the current user has access.
- Do not treat Soon/request-only entries as executable. If an action is missing, explain the limitation instead of inventing an API.

For a permitted HTTP call without a ready-made tool: [proxy](https://ctx4.me/docs/proxy-requests.md), [endpoint discovery](https://ctx4.me/docs/api-endpoints.md). API documentation does not issue keys or grant additional permissions.

---

# Getting started

Source: https://ctx4.me/docs/quickstart

## Send the prompt to your AI

[Copy the prompt](https://ctx4.me/connect) and send it in a regular chat. It links to the [common agent guide](https://ctx4.me/docs/agent-setup.md): the MCP address, basic tools and connection sequence. The agent will choose its client guide and help install Context4 skills.

## Approve access

The agent will configure MCP or a plugin using the method available to it. You approve Context4 sign-in, the workspace and CRM authorization in your browser. Passwords and keys are not sent to chat. Connecting AI and authorizing a work account are separate steps.

## Give your first task

For example: “Show open amoCRM deals and their owners.” The agent checks the actual result. If there is no data, it says so; if access is needed, it shows the next step.

## Manual setup

[ChatGPT](https://ctx4.me/docs/connect-chatgpt.md), [Claude](https://ctx4.me/docs/connect-claude.md), [Codex](https://ctx4.me/docs/connect-codex.md), [Claude Code](https://ctx4.me/docs/connect-claude-code.md), [Hermes](https://ctx4.me/docs/connect-hermes.md), [OpenClaw](https://ctx4.me/docs/connect-openclaw.md).

Install the [basic Context4 skills](https://ctx4.me/docs/skills.md). Each client has its own method: files, ZIP upload or a plugin. Saving a skill does not authorize a service. Cloud clients require reachable HTTPS addresses for documentation and MCP; local agents can use a local deployment. [Help](https://ctx4.me/docs/troubleshooting.md).

## ChatGPT

[Connect ChatGPT and install skills](https://ctx4.me/docs/connect-chatgpt.md).

## Claude

[Connect Claude and install skills](https://ctx4.me/docs/connect-claude.md).

## Codex

[Connect Codex and install skills](https://ctx4.me/docs/connect-codex.md).

## Claude Code

[Connect Claude Code and install skills](https://ctx4.me/docs/connect-claude-code.md).

## Hermes

[Connect Hermes and install skills](https://ctx4.me/docs/connect-hermes.md).

## OpenClaw

[Connect OpenClaw and install skills](https://ctx4.me/docs/connect-openclaw.md).

## Data and terms

Context4 is free. Operation content is proxied without persistent storage. Account and authorization data is processed separately. [Data handling](https://ctx4.me/docs/data-handling.md) · [Privacy](https://ctx4.me/privacy) · [Terms](https://ctx4.me/terms) · [Support and deletion](https://ctx4.me/support#delete).

---

# Core concepts

Source: https://ctx4.me/docs/core-concepts

## Workspace

A workspace brings together connections, settings and member access. Before acting, check which workspace you are using.

## Connector and connection

A connector describes a service's capabilities. A connection is an authorized account in your workspace. They are different things.

## Action and result

A tool has an input schema and a result schema. AI can make mistakes: check the selected account and the consequences of changes.

## Tool, endpoint and session

A tool is an action with an input schema and a published identifier. An endpoint is a provider HTTP method with a path, parameters and JSON Schema; it is discovered separately and does not automatically appear among MCP tools. [Proxy requests](https://ctx4.me/docs/proxy-requests.md) explains calling an endpoint through a connected account.

A session pins the available tool set and execution settings, including TTL, budget and read-only policy. An execution is a separate durable record of an individual call, its state, attempts and result. Neither a session's existence nor acceptance of a request means the provider operation succeeded.

## End user

In a server integration, `user_id` associates actions with an application's end user. It is an opaque reference, not a field for email or personal data. Multiple users of one workspace can have separate accounts for the same service. A shared account is available only with appropriate sharing and ACL settings.

---

# Connections

Source: https://ctx4.me/docs/connections

[Open this deployment's console and connections](https://console.ctx4.me/integrations).

## Choose a service

The [reference catalog](https://ctx4.me/apps) shows current implementations. Actual availability is determined by your workspace's published catalog.

## Authorize an account

Check the service address and required permissions before approving. OAuth connections use the provider's page; API keys are entered through the secure connection flow.

## Check the state

After returning to Context4, check the connection status. If there is an error, read the message and retry after resolving its cause. Do not send secrets to support.

## Multiple accounts

If the agent finds multiple connections, identify the intended one by its safe identifier and purpose. Do not automatically select the first account. Sharing is explicit and checked during execution, including tenant and principal; another user's connection does not become accessible merely because it is visible in the same organization.

## States

`pending` means an unfinished connection, `active` means the account is ready, `degraded` means limited operation, `failed` means an error and `revoked` means access was withdrawn. Active does not guarantee permission for every provider API method. For OAuth/credential flows, use the Context4 link and enter secrets only in the designated form.

A server integration can use its own OAuth auth config. The native API supports renewing authorization for an OAuth connection that has not yet become active, with version checking; this is not a universal refresh button for any account. [HTTP contracts](https://ctx4.me/docs/api-connections.md) define the exact conditions and fields.

---

# Actions and results

Source: https://ctx4.me/docs/actions

## Inspect the tool

Check its name, input schema and purpose. The public catalog provides reference information; permitted actions depend on the account.

## Complete the task

Before changing data, check the workspace, account and arguments. Do not rely on an extra confirmation if the client does not provide one.

## Check the result

An operation has a state and a result. Compare the result with the original service; when retrying, consider the selected action's idempotency.

## From an accepted request to completion

An execution can have states `requested`, `queued`, `running`, `retrying`, `succeeded`, `failed`, `rejected` and `cancelled`; see the [Execution schema](https://ctx4.me/docs/api-schemas-1.md#execution) for the current contract's exact enum. Distinguish admission refusal from provider failure. A result response can include a short-lived signed link for a large payload.

Before retrying a change, check the previous call's outcome. The network can fail after a provider has applied a write. For HTTP methods that support it, use one idempotency key per logical operation; raw proxy and mirror need separate care because a retry creates a new upstream call.

The [execution reference](https://ctx4.me/docs/api-executions.md) describes status, result, attempts and cancellation. Cancelling an operation does not promise to roll back a change already applied in an external service.

---

# Data and sync

Source: https://ctx4.me/docs/syncs

[Open this deployment's console and connections](https://console.ctx4.me/integrations).

## Choose a data type

Available types are listed on the connector page. If a type is not declared, do not assume it is supported.

## Configure sync

Use an available mode and schedule in the console. The presence of a data type does not imply identical latency or completeness across services.

## Check the state

Before using data, check the sync state and freshness. A source error must not be interpreted as an absence of records.

## What to check before creation

Retrieve the connector's available syncable entities and delivery capabilities. The entity schema, historical reading support, mode and schedule depend on the source. API source provider schema discovery preserves the metadata revision; it does not infer a schema from arbitrary records. Database schema discovery returns declared tables and fields; an empty database can have a valid empty schema.

## Sources and history

Context4 distinguishes object syncs from events without object storage. Provider-event subscriptions can exist without a Sync; an event does not imply that historical reading is available for that service. A historical export is a separate resource with its own state and cancellation. Its availability and boundaries depend on the source.

Schema discovery, database polling and CDC currently support PostgreSQL and SQL Server. MySQL and MongoDB variants remain in the public schemas but are deferred: discovery returns `400 validation_failed`, and creating a sync on such a source is refused as not found.

For database polling, use read-only credentials and a supported mode; the reading mode determines whether deletions are visible. Broker delivery, snapshot and replay do not imply the same guarantee for every provider. Check the actual run status and source limitations.

Exact settings, states, schema hash and fields: [syncs](https://ctx4.me/docs/api-syncs.md), [sources](https://ctx4.me/docs/api-sources.md), [events](https://ctx4.me/docs/api-events.md).

---

# Access and disconnection

Source: https://ctx4.me/docs/access-and-disconnect

[Open this deployment's console and connections](https://console.ctx4.me/integrations).

## Grant only what is needed

Connect only accounts you are authorized to manage. Check member permissions and tools before use.

## Revoke access

Disconnect the connection in Context4 and revoke permissions in the provider's settings. Rotate a key if it has been exposed.

## Data processing

Request and response content is proxied without persistent storage in Context4. Disconnection and account-data deletion are separate actions; the external AI rules apply to data it has already received. See the [Privacy Policy](https://ctx4.me/privacy), [Terms](https://ctx4.me/terms) and [data handling guide](https://ctx4.me/docs/data-handling.md).

## Three independent types of access

| Access | What to revoke |
| --- | --- |
| AI client to Context4 | OAuth grant or its token family |
| Application to Context4 API | API key in the console |
| Context4 to an external service | Connection and provider-side authorization |

Revoking one does not replace checking the others. For example, disconnecting an AI client does not remove a connected CRM account or delete your Context4 account. Removing a member or archiving a workspace stops subsequent OAuth MCP access.

## Shared accounts

Share an account only with the users who need it. For compat execution with a supplied `user_id`, the platform checks tenant, principal, sharing and deny-first ACL. An explicit `connected_account_id` without `user_id` is the exception: it uses the API key's tenant boundary without principal or sharing/deny-first ACL checks. A session can impose additional limits. Do not infer organization management permissions from a single technical API scope.

---

# How data is handled

Source: https://ctx4.me/docs/data-handling

## Request flow

```text
Your AI → Context4 → selected business service
Your AI ← Context4 ← service response
```

Context4 executes a permitted operation as a proxy. Request and response content is processed in memory during execution and result transfer. No persistent content store, chat history, CRM archive or response backups are created. Payloads and secrets are excluded from logs, queues and caches.

## Connection data

Account records, workspace permissions, connection settings and required authorization tokens exist separately from operation content. They enable sign-in and access on your behalf. They do not authorize advertising or model training using your data.

## What your AI receives

The AI client you select and authorize receives tool results. Its own retention and deletion rules continue to apply. Context4 cannot delete data from an existing conversation in another application. No storage in the proxy does not mean no processing by every participant.

## Corporate systems

Obtain authority from the system owner and a lawful basis for disclosure to your selected AI before connecting. Sign-in capability and OAuth consent do not replace these requirements. Check applicable international transfer requirements where data crosses borders. Arrange a processing agreement before disclosure if necessary.

## Disconnect and delete

Disconnecting stops use of the relevant connection secrets. Revoke the AI client MCP grant, Context4 API key and CRM grant separately. Contact [support](https://ctx4.me/support#delete) to delete your account and service data. Source-service and AI-client data rules apply separately.

The full contract is in the [Privacy Policy](https://ctx4.me/privacy) and [Terms of Use](https://ctx4.me/terms). [All revocation steps](https://ctx4.me/docs/access-and-disconnect.md).

---

# Errors and support

Source: https://ctx4.me/docs/troubleshooting

## Authorization did not finish

Check the selected account and the provider's integration availability. A private integration may not support connecting another organization.

## An action is unavailable

Check the workspace's published tools, permissions and version. An implementation in the public reference does not grant access automatically.

## Contact support

Describe the steps and error message, and include a safe operation identifier. Do not send passwords, tokens or confidential record contents. [Open support](https://ctx4.me/support).

---

# Connect ChatGPT

Source: https://ctx4.me/docs/connect-chatgpt

## What you need

- A ChatGPT account with Plugins access and permission to install a plugin or test MCP connection. Your organization may require administrator approval.
- A Context4 account and a workspace you can access.
- A business-service account authorized for the selected data and actions. Corporate connections require authority from the system owner.

Context4 is completely free. ChatGPT and source-service plans are set by their providers.

## Connect Context4

**ChatGPT connects through the Context4 plugin.** Configuring MCP in Codex or installing a CLI does not add a ChatGPT plugin.

1. Open Plugins in ChatGPT. If Context4 is available in your catalog, open its listing and install it. There is currently no verified public Context4 listing link on this page.
2. For a test connection, where your account allows it, use Plugins → plus → Add custom MCP server. In the Apps interface this option may be called Create. Enter Context4, the MCP URL below and OAuth.
3. Follow browser authorization to Context4, sign in, select a workspace and approve the requested access. Cancelled or denied sign-in does not complete setup.
4. Enable Context4 in the conversation tools. If the required option is missing, contact your administrator. An agent cannot enable a missing feature with a chat message.

MCP server for this environment:

```text
https://ctx4.me/mcp
```

Cloud ChatGPT requires a publicly reachable HTTPS server: it cannot reach localhost or your computer's local addresses. [Official OpenAI guide](https://help.openai.com/en/articles/12584461-connecting-custom-mcp-servers-in-chatgpt).

## Requested permissions

MCP OAuth uses the `mcp:tools` scope for available tools in the selected workspace. It does not automatically grant access to all your services. See [OAuth discovery](https://ctx4.me/.well-known/oauth-authorization-server) and [MCP authorization](https://ctx4.me/docs/mcp-oauth.md).

Each CRM or other service has separate authorization: review its consent screen and connector description. Permissions may allow reading, creating, changing or sending. Grant only what is necessary. Enter source-service passwords or keys through the designated connection flow, not an AI chat.

## Connect a business service

Ask the AI to find the connector and check existing connections. If access is missing, it should offer the supported authorization flow. Open the returned link, check the address, account and permissions and confirm yourself. [Connection console](https://console.ctx4.me/integrations). If a tool is unavailable, the AI should explain the limitation rather than present sample data as a real result.

## First request

> Show the available deals in amoCRM and help me understand what is in progress. Use real connection data; if access is missing, help me connect the account.

Check that the answer follows a real tool call. Make changes through a separate explicit request:

> Create a task to call the customer tomorrow. First confirm the deal, assignee and time with me.

Creation requires a corresponding tool and permissions. [Verify execution](https://ctx4.me/docs/actions.md).

## Skills

Install `context4` and `context4-setup`; add `context4-workflows` for cross-service tasks. [ChatGPT skill instructions](https://ctx4.me/docs/skills-chatgpt.md). A skill archive does not replace the plugin, an available ChatGPT feature or OAuth.

## Disconnect and delete

Disconnect Context4 in ChatGPT and revoke its MCP grant. To stop CRM access, also disconnect it in Context4 and revoke the grant in the CRM. Removing the plugin does not automatically perform every step.

Operation content is proxied without storage in Context4; account and authorization data is processed separately. Request account deletion through [support](https://ctx4.me/support#delete). OpenAI rules govern deletion of data already received by ChatGPT. [Data handling](https://ctx4.me/docs/data-handling.md) · [Revocation guide](https://ctx4.me/docs/access-and-disconnect.md) · [Privacy](https://ctx4.me/privacy) · [Terms](https://ctx4.me/terms).

---

# Skills for Codex

Source: https://ctx4.me/docs/skills-codex

## Save to a project

Save complete folders into `.agents/skills/<skill>/`. The personal scope for all projects is `~/.agents/skills/<skill>/`. Download and read the packages first:

```sh
context4_skill_tmp="$(mktemp -d)"
for skill in context4 context4-setup; do
  curl --fail --location "https://ctx4.me/skills/$skill/archive.zip" --output "$context4_skill_tmp/$skill.zip"
  unzip -l "$context4_skill_tmp/$skill.zip"
done
# Read SKILL.md and references before installing.
mkdir -p .agents/skills
for skill in context4 context4-setup; do
  unzip -n "$context4_skill_tmp/$skill.zip" -d .agents/skills
done
```

`unzip -n` does not overwrite files. If a folder already exists, compare versions: skipping it does not mean an update succeeded. In a new conversation, check that `context4` and `context4-setup` appear. Add `context4-workflows` in the same way for tasks across systems.

Configure [MCP](https://ctx4.me/docs/connect-codex.md) separately. [All files](https://ctx4.me/docs/skills-index.json). If the agent cannot access files, save them manually or use the instructions in the current chat without claiming persistent installation.

[Official specification](https://developers.openai.com/codex/skills/).

---

# Connect Claude

Source: https://ctx4.me/docs/connect-claude

This is **Claude web or desktop**, not Claude Code. [Claude Code has separate setup](https://ctx4.me/docs/connect-claude-code.md).

## What you need

- A Claude account with Connectors access and permission to add a remote connector; check your administrator's rules in an organization.
- A Context4 account, selected workspace and business-service account with the required permissions.
- Authority to transfer data to the selected AI when connecting a corporate system.

Context4 is free. Claude and business-service plans are set separately by their providers.

## Add a remote connector

1. Open Settings → Connectors in Claude. If Context4 is available in the directory, use its listing; where custom connectors are available, you can add your own remote connector.
2. Enter Context4 and the exact MCP URL for this environment:

```text
https://ctx4.me/mcp
```

3. Start connecting and follow browser authorization to Context4. Sign in, select an accessible workspace and approve access. Cancelled or denied sign-in does not complete setup.
4. Enable Context4 in the conversation tools and ask it to check available connections. If the feature is unavailable, contact your administrator.

Cloud Claude requires a publicly reachable HTTPS address. A local desktop extension is a different mechanism. The `claude mcp add` command belongs to Claude Code; it is not executed by messaging ordinary Claude. [Official guide](https://support.claude.com/en/articles/11725091-when-to-use-desktop-and-web-connectors).

## Permissions and business accounts

The MCP OAuth scope `mcp:tools` grants access to permitted tools in the selected workspace, not every service at once. [OAuth discovery](https://ctx4.me/.well-known/oauth-authorization-server) · [Technical guide](https://ctx4.me/docs/mcp-oauth.md).

CRMs and other services are connected separately: the AI finds a connector, checks existing access and returns an authorization link if required. Review the account, recipient and scopes on the consent screen. Enter API keys through the designated Context4 flow, never in chat. [Open connections](https://console.ctx4.me/integrations).

## First task

> Show deals in the connected CRM where we need to contact the customer. If the required data or permissions are unavailable, explain what is available and do not invent anything.

Fields and actions depend on the connector. Request writes explicitly and separately:

> Create a task to call the customer tomorrow. First confirm the deal, assignee and time.

The AI must use a real tool and report a confirmed result. [Verify execution](https://ctx4.me/docs/actions.md).

## Skills

Install `context4` and `context4-setup`; add `context4-workflows` for cross-service tasks. [Claude skill instructions](https://ctx4.me/docs/skills-claude.md). Skills do not replace a remote connector or authorization.

## Disconnect and data

Disconnect the connector in Claude and revoke its MCP grant. Separately disconnect the business account in Context4 and revoke its grant or key in the source service. Removing one connection does not revoke the others.

Context4 proxies operation content without persistent storage; account and authorization data is processed separately. Request account deletion through [support](https://ctx4.me/support#delete). Anthropic rules govern data already received by Claude. [Data handling](https://ctx4.me/docs/data-handling.md) · [Revocation guide](https://ctx4.me/docs/access-and-disconnect.md) · [Privacy](https://ctx4.me/privacy) · [Terms](https://ctx4.me/terms).

---

# Skills for Claude Code

Source: https://ctx4.me/docs/skills-claude-code

## Save to a project

Save complete folders into `.claude/skills/<skill>/`. The personal scope for all projects is `~/.claude/skills/<skill>/`. Download and read the packages first:

```sh
context4_skill_tmp="$(mktemp -d)"
for skill in context4 context4-setup; do
  curl --fail --location "https://ctx4.me/skills/$skill/archive.zip" --output "$context4_skill_tmp/$skill.zip"
  unzip -l "$context4_skill_tmp/$skill.zip"
done
# Read SKILL.md and references before installing.
mkdir -p .claude/skills
for skill in context4 context4-setup; do
  unzip -n "$context4_skill_tmp/$skill.zip" -d .claude/skills
done
```

`unzip -n` does not overwrite files. If a folder already exists, compare versions: skipping it does not mean an update succeeded. In a new conversation, check that `context4` and `context4-setup` appear. Add `context4-workflows` in the same way for tasks across systems.

Configure [MCP](https://ctx4.me/docs/connect-claude-code.md) separately. [All files](https://ctx4.me/docs/skills-index.json). If the agent cannot access files, save them manually or use the instructions in the current chat without claiming persistent installation.

[Official specification](https://code.claude.com/docs/en/skills).

---

# Connect Codex

Source: https://ctx4.me/docs/connect-codex

**Direct MCP is sufficient. A plugin is optional.** Use the application's MCP settings. If a terminal and Codex CLI are available:

```sh
codex mcp get context4
codex mcp add context4 --url 'https://ctx4.me/mcp'
codex mcp login context4
codex mcp get context4
```

If an entry already exists with the correct address, skip adding it. A missing entry on the first `get` means the server has not been configured yet. Ask about the user's intent if the address differs. Sign in using the client's link. If tools do not appear, refresh the session or open a new chat.

A plugin may become an additional installation method after publication; direct MCP remains available. [Official Codex MCP documentation](https://developers.openai.com/codex/mcp).

## Install Context4 skills

For normal setup, install `context4` and `context4-setup`. Add `context4-workflows` for tasks across systems. [Codex installation](https://ctx4.me/docs/skills-codex.md). Skills do not replace MCP or authorization.

[Universal agent instructions](https://ctx4.me/docs/agent-setup.md).

---

# Skills for Hermes

Source: https://ctx4.me/docs/skills-hermes

## Direct URL

Read [context4](https://ctx4.me/skills/context4/SKILL.md), [setup](https://ctx4.me/skills/context4-setup/SKILL.md), and their references before installation. Hermes downloads SKILL.md and explicitly linked files:

```sh
hermes skills install 'https://ctx4.me/skills/context4/SKILL.md'
hermes skills install 'https://ctx4.me/skills/context4-setup/SKILL.md'
```

The usual location is `~/.hermes/skills/`. Start a new session and check availability. The agent can save a complete package through `skill_manage`; do not silently overwrite edits. Optional: [context4-workflows](https://ctx4.me/skills/context4-workflows/SKILL.md). [MCP/OAuth](https://ctx4.me/docs/connect-hermes.md) is configured separately.

[Official installation guide](https://hermes-agent.nousresearch.com/docs/guides/work-with-skills/). The format is documented; end-to-end operation with Context4 has not been verified yet.

---

# Connect Claude Code

Source: https://ctx4.me/docs/connect-claude-code

This is a separate client with a terminal. Commands for this deployment's MCP:

```sh
claude mcp get context4
claude mcp add --transport http context4 'https://ctx4.me/mcp'
```

Reuse an existing suitable entry. In Claude Code, open `/mcp`, select Context4, and authorize in the browser. Reconnect the server if needed and check that tools appear.

A marketplace plugin may become an alternative after a real Context4 package is published, but direct MCP does not require one. [Claude Code MCP](https://code.claude.com/docs/en/mcp), [plugins](https://code.claude.com/docs/en/discover-plugins). The existing [/connect/claude](https://ctx4.me/connect/claude) address refers specifically to Claude Code.

## Install Context4 skills

For normal setup, install `context4` and `context4-setup`. Add `context4-workflows` for tasks across systems. [Claude Code installation](https://ctx4.me/docs/skills-claude-code.md). Skills do not replace MCP or authorization.

[Universal agent instructions](https://ctx4.me/docs/agent-setup.md).

---

# Skills for OpenClaw

Source: https://ctx4.me/docs/skills-openclaw

## Local package

Download the [context4 ZIP](https://ctx4.me/skills/context4/archive.zip) and [setup ZIP](https://ctx4.me/skills/context4-setup/archive.zip), extract to a temporary folder, and read SKILL.md and references. From the directory containing the extracted folders:

```sh
openclaw skills install ./context4 --as context4
openclaw skills install ./context4-setup --as context4-setup
```

The default location is the workspace's `skills/` directory. `--global` installs into `~/.openclaw/skills` for local agents. Preserve your edits and check the skills in a new session. These are local packages, not a published ClawHub listing.

Optional: [workflows ZIP](https://ctx4.me/skills/context4-workflows/archive.zip). Configure [MCP](https://ctx4.me/docs/connect-openclaw.md) separately. [Official installation guide](https://docs.openclaw.ai/tools/skills). End-to-end operation with Context4 has not been verified yet.

---

# Connect Hermes

Source: https://ctx4.me/docs/connect-hermes

Hermes Agent documents remote MCP and OAuth. This is MCP configuration for Hermes Agent. In its `~/.hermes/config.yaml` file, add the server to the existing `mcp_servers`, preserving other settings. Configuration for this deployment's MCP:

```yaml
mcp_servers:
  context4:
    url: "https://ctx4.me/mcp"
    auth: oauth
```

Then run:

```sh
hermes mcp login context4
```

Authorize using the client's link. Restart Hermes or run `/reload-mcp`, then check that tools appear.

End-to-end operation of Hermes with Context4 has not been confirmed yet. If OAuth fails, do not replace it by sharing secrets in chat. [Official Hermes MCP documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp).

## Install Context4 skills

For normal setup, install `context4` and `context4-setup`. Add `context4-workflows` for tasks across systems. [Hermes installation](https://ctx4.me/docs/skills-hermes.md). Skills do not replace MCP or authorization.

[Universal agent instructions](https://ctx4.me/docs/agent-setup.md).

---

# Skills for Claude

Source: https://ctx4.me/docs/skills-claude

## Upload to your account

This is Claude web/desktop, not Claude Code. Download and read the [context4 ZIP](https://ctx4.me/skills/context4/archive.zip) and [setup ZIP](https://ctx4.me/skills/context4-setup/archive.zip). Each archive contains one folder with SKILL.md and references.

Open Customize → Skills → plus → Create skill → Upload a skill. Upload and enable each package. Availability depends on your account, code execution, and organization rules. The agent prepares files and explains the steps; it must not claim an upload happened without an actual action.

Optional: [workflows ZIP](https://ctx4.me/skills/context4-workflows/archive.zip). Skills do not create a [remote connector](https://ctx4.me/docs/connect-claude.md). Cloud Claude needs reachable HTTPS addresses. If uploading is prohibited, use the [instructions](https://ctx4.me/docs/agent-setup.md) in the current conversation and state that no installation took place.

[Official instructions](https://support.claude.com/en/articles/12512180-use-skills-in-claude).

---

# Connect OpenClaw

Source: https://ctx4.me/docs/connect-openclaw

Use built-in MCP. A third-party bridge is not required. In Settings → MCP, add Context4 with the address `https://ctx4.me/mcp`, Streamable HTTP transport, and OAuth. Select Sign in as a user with permission to manage the server.

In the configuration, servers live in `mcp.servers`; OAuth is selected with `auth: "oauth"`. Check the full format against your version's documentation; preserve other servers and tool allow rules. Refresh the connection and check the agent's tools.

If your installed version does not support the required MCP/OAuth, tell the user. End-to-end compatibility between OpenClaw and Context4 has not been verified yet. [Official OpenClaw MCP documentation](https://docs.openclaw.ai/tools/mcp).

## Install Context4 skills

For normal setup, install `context4` and `context4-setup`. Add `context4-workflows` for tasks across systems. [OpenClaw installation](https://ctx4.me/docs/skills-openclaw.md). Skills do not replace MCP or authorization.

[Universal agent instructions](https://ctx4.me/docs/agent-setup.md).

---

# Skills for ChatGPT

Source: https://ctx4.me/docs/skills-chatgpt

## ChatGPT web

Normal setup requires a Context4 plugin with MCP and baseline skills. The [plugin source package](https://ctx4.me/skills/plugin.zip) contains plugin.json, mcp.json, and three skill folders with deployment addresses. This is a package for preparation and testing, not a published installation link. Downloading a ZIP does not install a plugin in ChatGPT.

After publication, install the actual plugin from an available catalog and confirm OAuth. Do not invent a catalog URL or attempt to install a web plugin by writing to `.agents/skills` on a computer.

[Manual MCP plugin configuration](https://ctx4.me/docs/connect-chatgpt.md) adds MCP but does not prove skill installation. Until supported package installation is available, use the [universal instructions](https://ctx4.me/docs/agent-setup.md) as guidance for the current chat.

## ChatGPT desktop

The official format supports standalone skills on desktop. If the environment can create skills, give the agent the [file index](https://ctx4.me/docs/skills-index.json) and ask it to save `context4` and `context4-setup` through a supported skill creator/installer. Check that they appear in Skills. Do not automatically assume this capability also exists on web.

[Official OpenAI format](https://developers.openai.com/codex/skills/). Cloud ChatGPT requires public HTTPS addresses for MCP and documentation; localhost is unreachable.

---

# Technical documentation

Source: https://ctx4.me/docs/api-reference

Context4's public surface consists of the HTTP API `/v1`, remote `/mcp`, OAuth for MCP and the Composio adapter at `/compat/context4/v1`. These are different ways to access shared connections and execution, subject to permissions, policies and quotas.

## HTTP API

[General rules and authorization](https://ctx4.me/docs/api.md) explains keys, errors, pagination and retries. The [full OpenAPI JSON](https://ctx4.me/docs/openapi.json) contains 66 operations on 45 paths and 61 named schemas; the reference below is generated from that same public contract.

| Chapter | Contents |
| --- | --- |
| [Tools and identity](https://ctx4.me/docs/api-tools.md) | Catalog, tool schema, current access scope |
| [Executions](https://ctx4.me/docs/api-executions.md) | Creation, list, state, attempts and cancellation |
| [Connections](https://ctx4.me/docs/api-connections.md) | Accounts, auth configs, stored provider schemas |
| [Sources and networks](https://ctx4.me/docs/api-sources.md) | Databases, credentials, discovery, network and schemas |
| [Sessions](https://ctx4.me/docs/api-sessions.md) | Creation, reading, updates and tool list |
| [Syncs](https://ctx4.me/docs/api-syncs.md) | Settings, runs, records, replay and exports |
| [Events](https://ctx4.me/docs/api-events.md) | Provider event catalog and subscriptions |
| [Provider HTTP](https://ctx4.me/docs/api-endpoints.md) | Discovery and mirror calls |
| [JSON Schema](https://ctx4.me/docs/api-schemas-1.md) | Complete request and response structures in four parts |

## AI and MCP

[Connection and protocol](https://ctx4.me/docs/ai-mcp.md), [five meta-tools with exact schemas](https://ctx4.me/docs/mcp-tools.md), [OAuth](https://ctx4.me/docs/mcp-oauth.md). Service tools load from the live catalog; there is no complete universal action list for every account.

## Direct HTTP and SDK

[Proxy requests](https://ctx4.me/docs/proxy-requests.md) explains paths, query parameters, bodies, authorization and restrictions. [Composio SDK](https://ctx4.me/docs/composio-sdk.md) describes compatible versions and differences from native contracts.

Public documentation describes client interfaces. Internal ingress, service-to-service controllers, service checks and operator settings are not client APIs.

## Machine-readable reference

[OpenAPI JSON](https://ctx4.me/docs/openapi.json), [HTTP and MCP index with schemas](https://ctx4.me/docs/api-index.json), [compat route inventory](https://ctx4.me/docs/compat-routes.json), [AI instructions](https://ctx4.me/llms.txt), [full documentation as one text](https://ctx4.me/llms-full.txt). Retrieve any chapter as Markdown by appending `.md` to its address.

The [public connector and action catalog in JSON](https://ctx4.me/docs/connectors.json) contains versions, authorization methods and action keys. It is a catalog snapshot, not confirmation of access in the current account: check schemas and availability through discovery.

---

# API authorization and rules

Source: https://ctx4.me/docs/api

## Address and authorization

This deployment's API address: `https://ctx4.me/v1`. [Console and connections](https://console.ctx4.me/integrations). The `CONTEXT4_API_KEY` variable holds your secret server-environment key; the documentation does not substitute it.

```bash
curl "https://ctx4.me/v1/identity" \
  -H "Authorization: Bearer $CONTEXT4_API_KEY"
```

A key is issued in the console and displayed once. Its format is `ctx4_<env>_<secret>`. A key is scoped to an organization, workspace and set of capabilities. A resource belonging to another tenant returns `404 not_found`. The required capability for each method appears in the [reference](https://ctx4.me/docs/api-reference.md).

| Capability | Purpose |
| --- | --- |
| `tools:read` | Tools and HTTP method catalog |
| `executions:read`, `executions:write` | Read and create executions; proxy also requires write |
| `connections:read`, `connections:write` | Connections, auth configs and sources |
| `connections:manage` | Additional permission to manage other users' connections within a tenant; requires connections:write |
| `tool-sessions:read`, `tool-sessions:write` | Tool sessions |
| `syncs:read`, `syncs:write` | Syncs and exports |
| `events:read`, `events:write` | Events and subscriptions |

A missing capability produces `403 capability_missing`. An ordinary key does not gain permission to change another user's connection merely by having `connections:write`. MCP OAuth does not delegate `connections:manage`.

The interface is intended for server use. CORS is not enabled for `/v1`, `/mcp` or compat. Do not put a bearer key in browser code, a URL or a public repository.

## Request bodies and identifiers

Send JSON with `Content-Type: application/json`. The input body limit is 65,536 bytes. Headers and the request line are bounded by the listener; a long vendor URL may be rejected before routing.

`X-Request-Id` is optional: it accepts 1–128 characters matching `[A-Za-z0-9][A-Za-z0-9._:-]{0,127}`. Without it, the server generates a UUID. An invalid value is rejected with `422`; the response includes a new safe request ID. Store `X-Request-Id` and the execution ID for diagnosis.

## Idempotency and retries

Send `Idempotency-Key` when declared in the method's parameters. Its value is 8–128 characters from `[A-Za-z0-9._:-]`. Repeating the same request with the same key returns the original result; a changed body with the previous key produces `409 idempotency_conflict`. Choose a new key for a new intentional operation.

`202` when creating an execution means acceptance or a recorded refusal, not a successful provider change. Read `status`, `denial_code` and the address in `Location`, then poll the execution. Do not automatically repeat a write after a timeout: it may have been applied.

The current `idempotency_conflict` does not distinguish an in-progress request from a mismatched body; it does not promise `Retry-After`. Check the original request and operation state. Mirror API and raw proxy are not idempotent: each call may send a new request to the provider.

## Pagination

Lists use opaque `cursor` and `next_cursor`. Pass the returned cursor unchanged until `null`; do not construct it from an ID. The general `limit` is 1–100, default 20; the reference lists each method's exact parameters and constraints. A cursor is limited to 400 characters. Keep filters unchanged between pages.

Vendor pagination is a separate provider contract: see `paging` in the endpoint descriptor. A Context4 cursor does not imply automatic retrieval of all upstream pages.

## Errors and limits

Platform errors return `application/problem+json` with `type`, `code`, `title`, `status`, `request_id`. Exact enums and fields: [Problem](https://ctx4.me/docs/api-schemas-1.md#problem). Internal causes and credentials are not exposed to the client.

| HTTP | Client action |
| --- | --- |
| 400 | Correct parameters or body; check the schema |
| 401 | Check the key, expiry and revocation |
| 403 | Check capabilities, ownership, policy and session restrictions |
| 404 | Check the ID and access scope |
| 409 | Check version, account or idempotency key conflicts |
| 429 | Respect `Retry-After` if returned |
| 500 | Save the request ID for support |
| 503 | Check service availability; a write retry requires checking its outcome |

`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` describe the API key's minute window; reset is the number of seconds until reset. If Redis is unavailable, writes fail closed with `503`; reads may continue without rate-limit headers. Execution quota and HTTP request rate limits are separate checks.

---

# AI and MCP

Source: https://ctx4.me/docs/ai-mcp

## Connection

This deployment's MCP address: `https://ctx4.me/mcp`. Cloud clients need a reachable HTTPS address. A client supporting remote HTTP MCP discovers OAuth, opens browser sign-in and requests access to the selected workspace. This flow does not require a Context4 API key. The [quickstart](https://ctx4.me/docs/quickstart.md) begins with a ready-made prompt on the [connection page](https://ctx4.me/connect).

Do not construct a provider authorization URL manually. Context4 returns the link. Signing in to Context4 and connecting a provider account are separate permissions. A provider may require its own key, OAuth consent or credentials entered in a secure form.

Automations can use an API key in `Authorization: Bearer`, `x-consumer-api-key` or `x-api-key`, according to client configuration. The secret is not included in the URL. The HTTP resource supports `POST`, `GET`, `DELETE /mcp`; transport is Streamable HTTP.

## Agent sequence

1. `CONTEXT4_SEARCH_TOOLS`: find an action for the task; check connection status and tags.
2. `CONTEXT4_GET_TOOL_SCHEMAS`: retrieve exact input/output schemas for the discovered `tool_slug` values.
3. `CONTEXT4_MANAGE_CONNECTIONS` with `action: list`: check accounts. With `action: connect`, obtain an existing active connection or a hosted Connect Link.
4. Show the returned link to the user. If `connection_id` is available, call `CONTEXT4_WAIT_FOR_CONNECTIONS`; repeat according to `retry_after_ms` until active or a terminal refusal.
5. `CONTEXT4_MULTI_EXECUTE_TOOL`: submit 1–20 tools with schema-based arguments; explicitly specify `connection_id` if multiple accounts exist.
6. Check each `results` item: `succeeded`, `pending` or `error`. Report empty data as empty; do not present pending as success.

The complete set and schemas: [MCP tools](https://ctx4.me/docs/mcp-tools.md). Search ranks matches and is not a complete integration inventory. Tags `read-only`, `destructive`, `idempotent`, `open-world`, `curated` help selection; all `tags` must match, while any matching `exclude_tags` excludes a result.

## Sessions and dynamic tools

The global `/mcp` exposes five stable meta-tools. The session address `/mcp?session=` is returned during session creation and exposes its tool snapshot, meta-tools enabled by feature flags and `context4.get_execution`. Provider tool schemas depend on the pinned catalog version; use the actual `tools/list` response.

`context4.get_execution` accepts an object whose sole required string field is `execution_id`; the schema declares no additional fields. It retrieves the state and terminal result of a pending call. SDK session mode also publishes enabled aliases `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_GET_TOOL_SCHEMAS`, `COMPOSIO_MANAGE_CONNECTIONS`, `COMPOSIO_WAIT_FOR_CONNECTIONS`, `COMPOSIO_MULTI_EXECUTE_TOOL`. They route to the same handlers.

If the session's workbench flag is enabled, `COMPOSIO_REMOTE_WORKBENCH` and `COMPOSIO_REMOTE_BASH_TOOL` may be listed: they return `not_supported` because this deployment does not implement a remote sandbox. A listed name does not promise a working shell.

A `readOnly` session permits only tools tagged `read-only`; a tool without the tag is treated as a write. Search and meta-execution within that session inherit the restriction. Session TTL, revocation and call budget are also checked during execution.

## Results and errors

An MCP response includes `structuredContent` and text JSON in `content`. Unknown names or invalid arguments produce an error result with `isError: true`; transport success alone does not mean tool success. Check errors separately in each batch `results` item.

`connection_required` requires connection, `connection_ambiguous` requires account selection, `authorization_pending` requires waiting and `invalid_arguments` requires checking the schema. For `permission_denied` and `rate_limited`, address the restriction; for `execution_pending`, use the execution ID and specified interval. `execution_failed` does not prove that an external write was not applied.

Read access does not authorize an agent to perform a test write. Make the first check a safe available read. Deletions, changes and messages require an explicit user task.

---

# MCP tool reference

Source: https://ctx4.me/docs/mcp-tools

This deployment's MCP: `https://ctx4.me/mcp`.

This is the complete stable set for the global `/mcp`. Service-specific tools are discovered through search and schema retrieval; their availability depends on the catalog and permissions. Connection and error handling rules: [AI and MCP](https://ctx4.me/docs/ai-mcp.md). Strict input schemas reject unknown fields. `arguments` also undergoes serialization validation and a 65,536-character JSON limit; custom Zod validation cannot be represented by standard JSON Schema.

## CONTEXT4_SEARCH_TOOLS

Search Context4 for provider tools needed for a task. Results include connection readiness.

### Input schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 500
    },
    "connector_id": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]{1,78}$"
        },
        {
          "type": "string",
          "minLength": 2,
          "maxLength": 80,
          "pattern": "^[a-z][a-z0-9-]*$"
        }
      ]
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "tags": {
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "read-only",
          "destructive",
          "idempotent",
          "open-world",
          "curated"
        ]
      }
    },
    "exclude_tags": {
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "read-only",
          "destructive",
          "idempotent",
          "open-world",
          "curated"
        ]
      }
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

### Output schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tool_slug": {
            "type": "string",
            "minLength": 3,
            "maxLength": 240,
            "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_.-]*$"
          },
          "connector_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]{1,78}$"
              },
              {
                "type": "string",
                "minLength": 2,
                "maxLength": 80,
                "pattern": "^[a-z][a-z0-9-]*$"
              }
            ]
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "tags": {
            "maxItems": 5,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "read-only",
                "destructive",
                "idempotent",
                "open-world",
                "curated"
              ]
            }
          },
          "connection_status": {
            "type": "string",
            "enum": [
              "connected",
              "connection_required",
              "multiple_connections"
            ]
          }
        },
        "required": [
          "tool_slug",
          "connector_id",
          "name",
          "description",
          "connection_status"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "tools",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## CONTEXT4_GET_TOOL_SCHEMAS

Get exact input and output schemas for tool slugs returned by tool search.

### Input schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "tool_slugs": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 240,
        "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_.-]*$"
      }
    }
  },
  "required": [
    "tool_slugs"
  ],
  "additionalProperties": false
}
```

### Output schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tool_slug": {
            "type": "string",
            "minLength": 3,
            "maxLength": 240,
            "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_.-]*$"
          },
          "connector_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]{1,78}$"
              },
              {
                "type": "string",
                "minLength": 2,
                "maxLength": 80,
                "pattern": "^[a-z][a-z0-9-]*$"
              }
            ]
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "input_schema": {},
          "output_schema": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "tool_slug",
          "connector_id",
          "name",
          "description",
          "input_schema",
          "output_schema"
        ],
        "additionalProperties": false
      }
    },
    "missing": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 240,
        "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_.-]*$"
      }
    }
  },
  "required": [
    "tools",
    "missing"
  ],
  "additionalProperties": false
}
```

## CONTEXT4_MANAGE_CONNECTIONS

List connected accounts or create a hosted authorization link.

### Input schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "const": "list"
        },
        "connector_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,78}$"
            },
            {
              "type": "string",
              "minLength": 2,
              "maxLength": 80,
              "pattern": "^[a-z][a-z0-9-]*$"
            }
          ]
        }
      },
      "required": [
        "action",
        "connector_id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "const": "connect"
        },
        "connector_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,78}$"
            },
            {
              "type": "string",
              "minLength": 2,
              "maxLength": 80,
              "pattern": "^[a-z][a-z0-9-]*$"
            }
          ]
        },
        "display_name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 120
        },
        "return_path": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512,
          "pattern": "^\\/(?!\\/)[A-Za-z0-9/_.-]*$"
        }
      },
      "required": [
        "action",
        "connector_id"
      ],
      "additionalProperties": false
    }
  ]
}
```

### Output schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "const": "listed"
        },
        "connections": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "connection_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              "connector_id": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9-]{1,78}$"
                  },
                  {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 80,
                    "pattern": "^[a-z][a-z0-9-]*$"
                  }
                ]
              },
              "display_name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "active",
                  "degraded",
                  "revoked",
                  "failed"
                ]
              }
            },
            "required": [
              "connection_id",
              "connector_id",
              "display_name",
              "status"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "status",
        "connections"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "const": "authorization_required"
        },
        "connection_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "connect_url": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "instruction": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        }
      },
      "required": [
        "status",
        "connection_id",
        "connect_url",
        "expires_at",
        "instruction"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "const": "credentials_required"
        },
        "connect_url": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri"
        },
        "instruction": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        }
      },
      "required": [
        "status",
        "connect_url",
        "instruction"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "const": "active"
        },
        "connection": {
          "type": "object",
          "properties": {
            "connection_id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            "connector_id": {
              "anyOf": [
                {
                  "type": "string",
                  "pattern": "^[a-z0-9][a-z0-9-]{1,78}$"
                },
                {
                  "type": "string",
                  "minLength": 2,
                  "maxLength": 80,
                  "pattern": "^[a-z][a-z0-9-]*$"
                }
              ]
            },
            "display_name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "active",
                "degraded",
                "revoked",
                "failed"
              ]
            }
          },
          "required": [
            "connection_id",
            "connector_id",
            "display_name",
            "status"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "status",
        "connection"
      ],
      "additionalProperties": false
    }
  ]
}
```

## CONTEXT4_WAIT_FOR_CONNECTIONS

Wait for a hosted authorization flow to become active.

### Input schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "timeout_seconds": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 60
    }
  },
  "required": [
    "connection_id"
  ],
  "additionalProperties": false
}
```

### Output schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "pending",
        "failed",
        "revoked",
        "degraded"
      ]
    },
    "connection": {
      "type": "object",
      "properties": {
        "connection_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "connector_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{1,78}$"
            },
            {
              "type": "string",
              "minLength": 2,
              "maxLength": 80,
              "pattern": "^[a-z][a-z0-9-]*$"
            }
          ]
        },
        "display_name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "degraded",
            "revoked",
            "failed"
          ]
        }
      },
      "required": [
        "connection_id",
        "connector_id",
        "display_name",
        "status"
      ],
      "additionalProperties": false
    },
    "retry_after_ms": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status",
    "connection",
    "retry_after_ms"
  ],
  "additionalProperties": false
}
```

## CONTEXT4_MULTI_EXECUTE_TOOL

Execute up to 20 discovered tools through tenant-scoped connections.

### Input schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "tools": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tool_slug": {
            "type": "string",
            "minLength": 3,
            "maxLength": 240,
            "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_.-]*$"
          },
          "arguments": {},
          "connection_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          }
        },
        "required": [
          "tool_slug",
          "arguments"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "tools"
  ],
  "additionalProperties": false
}
```

### Output schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "const": "succeeded"
              },
              "tool_slug": {
                "type": "string",
                "minLength": 3,
                "maxLength": 240,
                "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_.-]*$"
              },
              "execution_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              "result": {}
            },
            "required": [
              "status",
              "tool_slug",
              "execution_id",
              "result"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "const": "pending"
              },
              "tool_slug": {
                "type": "string",
                "minLength": 3,
                "maxLength": 240,
                "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_.-]*$"
              },
              "execution_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              "retry_after_ms": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "status",
              "tool_slug",
              "execution_id",
              "retry_after_ms"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "const": "error"
              },
              "tool_slug": {
                "type": "string",
                "minLength": 3,
                "maxLength": 240,
                "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_.-]*$"
              },
              "error_code": {
                "type": "string",
                "enum": [
                  "authentication_required",
                  "permission_denied",
                  "connection_required",
                  "connection_ambiguous",
                  "connection_default_required",
                  "workspace_changed",
                  "authorization_pending",
                  "tool_not_found",
                  "invalid_arguments",
                  "rate_limited",
                  "execution_pending",
                  "execution_failed",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              }
            },
            "required": [
              "status",
              "tool_slug",
              "error_code",
              "message"
            ],
            "additionalProperties": false
          }
        ]
      }
    }
  },
  "required": [
    "results"
  ],
  "additionalProperties": false
}
```

---

# OAuth for MCP

Source: https://ctx4.me/docs/mcp-oauth

## Deployment addresses

- MCP resource: `https://ctx4.me/mcp`.
- [Resource discovery](https://ctx4.me/.well-known/oauth-protected-resource/mcp).
- [OAuth discovery](https://ctx4.me/.well-known/oauth-authorization-server).

Obtain full authorize, token, register and revoke addresses from this deployment's discovery. The server returns consent and provider authorization URLs: do not construct them manually from examples.

## Public routes

| Method and path | Purpose | Input and result |
| --- | --- | --- |
| `GET https://ctx4.me/.well-known/oauth-protected-resource/mcp` | Resource discovery | Metadata with authorization server and MCP resource |
| `GET https://ctx4.me/.well-known/oauth-authorization-server` | OAuth discovery | Endpoint URLs, scope and supported grants |
| `POST https://ctx4.me/oauth/register` | Client registration | JSON with redirect URIs; client ID, public client without a secret |
| `GET https://ctx4.me/oauth/authorize` | Start authorization code flow | Query `client_id`, `redirect_uri`, `response_type=code`, `scope=mcp:tools`, `resource`, `code_challenge`, `code_challenge_method=S256`, `state`; browser redirect |
| `GET https://ctx4.me/oauth/consent` | Approval page | Continue browser consent in the selected workspace |
| `POST https://ctx4.me/oauth/token` | Code exchange and refresh | Form-urlencoded; tokens and expiry |
| `POST https://ctx4.me/oauth/revoke` | Revoke token family | Form-urlencoded `token`: access or refresh token |
| `POST https://ctx4.me/mcp`, `GET https://ctx4.me/mcp`, `DELETE https://ctx4.me/mcp` | MCP resource | MCP messages and lifecycle, bearer access token |

The client builds URLs from discovery. Do not invent an authorization URL from an example. This deployment's resource is `https://ctx4.me/mcp`; public clients require a reachable HTTPS address. A public client uses `token_endpoint_auth_method=none` and PKCE S256.

## Registration and redirects

A redirect URI must exactly match a registered URI. HTTPS and native-client loopback callbacks are permitted. Wildcards, fragments, URL credentials and non-loopback HTTP are rejected. The public MCP resource must have a stable HTTPS address.

## Code exchange

`grant_type=authorization_code` requires `code`, `client_id`, `redirect_uri`, `code_verifier`, `resource`. The code verifier is a string of 43–128 characters. The code is single-use and valid for five minutes. `grant_type=refresh_token` requires `refresh_token`, `client_id`, `resource`.

An access token is opaque and valid for 15 minutes. The refresh token rotates on refresh; the family lifetime is 30 days. Reuse of a consumed refresh token revokes the family. Store the latest refresh token atomically.

OAuth errors use `{error, error_description}`, rather than the general Problem API; token responses are not cached. A consent or code-exchange error must not be bypassed by repeating a provider write.

## What a grant permits

A grant provides workspace MCP access while preserving existing permissions and restrictions. It does not create a new provider account. An existing active connection may be reused; when several exist, the agent asks you to choose.

Every OAuth MCP request checks current membership and workspace state. Token revocation, member removal, changes to the membership epoch, workspace archival and grant expiry end access. Revoking MCP OAuth is distinct from revoking provider credentials: [access chapter](https://ctx4.me/docs/access-and-disconnect.md).

---

# Provider proxy requests

Source: https://ctx4.me/docs/proxy-requests

## Choosing an interface

| Option | When to use it | Boundary |
| --- | --- | --- |
| Mirror `/v1/api/` | Call an HTTP method from the endpoint catalog | Published method and template only; JSON Schema is validated |
| Composio `tools/execute/proxy` | Raw call to a connected service API without a tool wrapper | Relative path within this connector's API; no tool schema |
| Session proxy | Raw call within an SDK session | Additionally session TTL, status, budget and pinned account |

Proxy requests let you call provider methods that have no separate tool. They do not provide arbitrary HTTP access to any address. The connection and connector configuration determine the provider, credentials and base address. For some connectors the origin comes from the connection and undergoes egress validation.

## Discovering a mirror endpoint

1. Retrieve `GET /v1/connectors/{connectorId}/endpoints` with `tools:read`. Filters: `q`, `group`, `include_removed`, `cursor`, `limit`.
2. Select an endpoint and request `GET /v1/connectors/{connectorId}/endpoint?method=GET&path=...`. `path` is the catalog template; encode it as a query value.
3. Read `input_schema`, `output_schema`, `risk`, `sensitive`, `idempotent`, `paging` and `descriptor_digest`. The input schema contains exact vendor fields; the format depends on the provider.
4. Fill in parameters and call its `call_url` with the described method.

[Complete discovery and mirror contract](https://ctx4.me/docs/api-endpoints.md). An endpoint ID consists of a method and path template. A removed entry may appear with `include_removed=true`, but cannot be executed. An endpoint does not automatically become an MCP tool.

## Mirror: request and response

```bash
curl "https://ctx4.me/v1/api/amocrm/api/v4/leads/7" \
  -H "Authorization: Bearer $CONTEXT4_API_KEY" \
  -H "Context4-Connection-Id: $CONTEXT4_CONNECTION_ID"
```

This is a GET request example applicable when the endpoint is in your catalog and the account can access the deal. Obtain the origin and keys from your environment. Bodyless methods have no body; for JSON writes, send vendor JSON directly. Mirror supports GET, POST, PUT, PATCH, DELETE; HEAD returns `405` and executes nothing.

The path mirrors the provider path after `/v1/api/{connectorId}/`. Send `/` literally or encode the entire vendorPath as one segment. A slash within a parameter value is `%2F`, or `%252F` when encoding the entire path. It is permitted only within a parameter of a known template; `.` and `..` parts are prohibited.

Query parameters and declared vendor headers are validated against the input schema. Arrays use repeated names or a delimiter according to the descriptor; unknown query parameters and repeated scalar parameters are rejected. Do not assume every incoming header is forwarded to the provider.

Calls require `executions:write`, including GET. `Context4-Connection-Id` is required; a different connector's connection or a revoked connection produces a platform conflict. An unknown endpoint returns `404` before an upstream request; invalid vendor parameters return `400` before execution creation.

The response preserves the provider's HTTP status and JSON body, and permitted `etag`/`retry-after` headers. `Context4-Origin: provider` distinguishes it from a platform error; `Context4-Execution-Id` associates the call with an execution. A platform error has `Context4-Origin: platform` and problem JSON. Do not treat every 403 as a policy error: check the origin.

The mirror catalog includes operations that accept and return JSON. Multipart, form bodies, arbitrary bytes and redirect-only downloads are not promised. An unavailable provider, timeout or non-JSON response can produce `503`. Each mirror call is a new request, even with a repeated Idempotency-Key.

## Raw Composio proxy

`POST /compat/context4/v1/api/v3.1/tools/execute/proxy` accepts:

```json
{
  "connected_account_id": "UUID of the selected connection",
  "endpoint": "/api/v4/leads",
  "method": "GET",
  "parameters": [
    { "name": "limit", "type": "query", "value": 10 }
  ]
}
```

Substitute a real UUID. `method`: GET, POST, PUT, DELETE, PATCH, HEAD. `endpoint` is a relative path from the connector's API base, starting with `/`. `parameters` is an array of objects with `name`, `type` (`header` or `query`) and string/numeric `value`; `in` is accepted instead of `type`. Optional `body` is JSON. Repeating a name in this legacy array replaces its previous value; for vendor arrays, prefer mirror with an explicit serialization schema.

The result is a JSON envelope `{status, data, headers}`. The compat request's own HTTP status differs from upstream `status`. Policy refusal returns 403, quota returns 429 and an unavailable account returns 404; permanent input/provider rejection maps to a validation error, transient failure to 503.

When `user_id` is supplied, the selected account is checked for usability by that principal. Optional `borrowers` narrows the owner set to the listed users and the principal; it does not remove the tenant boundary. With multiple accounts, choose `connected_account_id` explicitly. Session proxy uses its pinned account and session restrictions.

## Security and retry boundaries

Absolute URLs, `//host`, traversal, backslashes, raw fragments and control characters are prohibited. Raw proxy does not accept encoded slashes to bypass a template. Connected-service credentials are inserted by the server: do not send a provider token through proxy.

Caller headers `Authorization`, `Proxy-Authorization`, `Cookie`, `Cookie2`, `x-api-key` are prohibited. Transport control headers (`base-url-override`, `connection-id`, `provider-config-key`, `retries`, `retry-on`, `decompress`, `forward-headers-on-redirect`, `nango-*`) are also rejected. Hop-by-hop headers are removed. A Context4 bearer authenticates to Context4 and does not become a provider credential.

Raw proxy bypasses the tool wrapper schema while retaining tenant, policy, quota, rate limit and audit checks. This does not promise access to every endpoint regardless of connector and transport capabilities. Check the provider's documentation and operation availability. After a write timeout, verify the outcome: absence of a response does not prove absence of an effect.

---

# Composio SDK

Source: https://ctx4.me/docs/composio-sdk

For SDK integration, use Composio with base URL `https://ctx4.me/compat/context4/v1` and a Context4 API key. A separate Context4 SDK is not required. The SDK appends its own `/api/v3.1/...` path; do not add it to the base URL twice.

## Supported version cohorts

| Cohort | Versions |
| --- | --- |
| Legacy | `@composio/core@0.13.1`, `@composio/client@0.1.0-alpha.74` |
| Tool Router | `@composio/core@0.14.0` |
| Sessions/Mastra | `@composio/client@0.1.0-alpha.76`, `@composio/core@0.17.0`, `@composio/mastra@0.10.3`, strict MastraProvider |

Compatibility for a specific cohort does not imply full compatibility with any future SDK. The [complete compat HTTP route inventory](https://ctx4.me/docs/compat-api-reference.md) lists methods, paths, capabilities and statuses. Native `/v1` requests are described by a separate [OpenAPI](https://ctx4.me/docs/openapi.json); do not automatically transfer field names between them.

## Discovery and execution

The tool catalog, toolkit/auth configs, connected account lifecycle, Tool Router sessions, session tools and direct execute use SDK contracts. `user_id` is an opaque end-user identifier; do not put email or personal data there. An explicit account must be accessible to the given principal and tenant. Auth-config UUIDs match exactly; multiple IDs form a union intersected with the toolkit filter.

Ordinary direct execute accepts SDK `arguments`, the selected `connected_account_id` and, when needed, `user_id`. Obtain tool slugs through discovery. Do not substitute a guessed action name when the exact slug is missing. Retrieve the input schema first; account availability alone does not guarantee permission for an action.

Creating a session without `Idempotency-Key` creates a new session on every request. An explicit key replays the original, preserving TTL and policy. An explicit idempotency key on direct execute retains the helper session for a 24-hour replay window; the same account and arguments return the original `log_id`. Changed arguments conflict. Without an explicit key, executions are independent and the helper lifetime is 15 minutes.

Session search and execute are bounded by the session snapshot, flags and read-only policy. A session returns its dynamic MCP URL; copy it from the result. The [MCP reference](https://ctx4.me/docs/ai-mcp.md) explains aliases and polling.

## Envelope and negative confirmation

Check SDK fields `successful`, `error`, `data` and `log_id`; HTTP 200 alone is not sufficient evidence that an action succeeded. Native Execution state and payload have a different shape.

Sometimes a terminal failure contains `data.failure_effect: not_applied` and `data.execution_id`: this is recorded confirmation that the write was not applied. Currently it is limited to a single-attempt amoCRM lead UPDATE with an explicit 400 refusal. Absence of the field proves nothing: timeouts, unknown responses and composite operations may have external effects. Do not infer “safe to retry” from an error code alone.

## Proxy, files and limitations

[Raw proxy](https://ctx4.me/docs/proxy-requests.md) uses `endpoint`, `method`, `parameters`, optional `body` and a selected connected account. Session proxy also applies session gates. The file API provides upload request/list and session mount URLs; content is uploaded to the returned presigned URL, not as an arbitrary large public API body. Mount availability depends on deployment configuration.

Compat trigger discovery is an intentional stub: its list is empty, retrieve returns not-found, and create/delete return `501 trigger_compat_not_implemented`. Native provider-event subscriptions and syncs do not create Composio trigger parity. Workbench/bash may be listed when their flag is enabled but return `not_supported`. Custom tools and external MCP toolkit connection should not be considered complete merely because a configuration resource exists.

The first-party workflow engine's external endpoint automations use a separate platform contract. For client applications, the public entry to the raw endpoint catalog is [native discovery and mirror](https://ctx4.me/docs/api-endpoints.md).

---

# Tools and identity

Source: https://ctx4.me/docs/api-tools

Generated from the public Context4 OpenAPI. Authenticate with `Authorization: Bearer` and an API key. General rules: [API](https://ctx4.me/docs/api.md). Full contract: [OpenAPI JSON](https://ctx4.me/docs/openapi.json). In the JSON below, `$ref` points to a named schema in the Schemas section.

## listTools

`GET /v1/tools`

Deployment URL: `https://ctx4.me/v1/tools`. Replace parameters in braces with actual IDs from the API.

List published tools

Capability: `tools:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connector_id` | query | no | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `search` | query | no | &#123;"type":"string","minLength":1,"maxLength":120&#125;  |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"&#125; Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Published tools (flattened connector actions) | `application/json` [ToolListResponse](https://ctx4.me/docs/api-schemas-1.md#toollistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getTool

`GET /v1/tools/{toolId}`

Deployment URL: `https://ctx4.me/v1/tools/{toolId}`. Replace parameters in braces with actual IDs from the API.

Get one tool with its JSON schemas

Capability: `tools:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `toolId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;\\.[a-z0-9][a-z0-9_.]&#123;1,78&#125;$","example":"bitrix24.contact.create"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Tool detail with pinned input/output schemas | `application/json` [ToolDetail](https://ctx4.me/docs/api-schemas-1.md#tooldetail) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getIdentity

`GET /v1/identity`

Deployment URL: `https://ctx4.me/v1/identity`. Replace parameters in braces with actual IDs from the API.

Get the authenticated credential's tenant

Capability: `connections:read`.

The contract defines no additional parameters.

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Verified organization and workspace; no credential material | `application/json` [PublicIdentity](https://ctx4.me/docs/api-schemas-1.md#publicidentity) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

---

# Business workflows: two services, one task

Source: https://ctx4.me/docs/business-cases

Your CRM knows whom you promised to call back. Telephony knows whether the conversation happened. A finance service knows which payments have been recorded. When AI receives data from two systems, it can prepare the next step using both sides.

The external examples below are followed by four workflows to implement through Context4. These are agent setup instructions, not reports of completed Context4 deployments. We have not measured time savings or sales growth from them.

## What companies already do

**WowSpeak online school: amoCRM + Wazzup.** In Wazzup's published case study, the school uses a customer's CRM status and return date for automated messages. Wazzup also sends questionnaires and lesson reminders. This illustrates combining sales data with a communication channel; the implementation uses the integration described in the case study. [WowSpeak case study by Wazzup](https://wazzup24.ru/blog/kejs-wowspeak/).

**ActivSports: amoCRM + Wazzup24.** Integrator Aspire describes connecting Wazzup24 to amoCRM to communicate with customers on WhatsApp from the CRM. The source identifies a specific company and pair of systems. This project's results are not Context4 results. [Aspire implementation case study](https://startup.aspire.agency/work/2024-activsports-wazzup24-amocrm).

Providers also document workflows for which we do not claim a specific customer:

- MANGO OFFICE describes forwarding missed calls to Bitrix24 and tracking their handling. [Bitrix24 and MANGO OFFICE integration](https://developers.mango-office.ru/support/4_integratsii/1_vse-integratsii/16_bitrix24/3_obrabotka_zvonkov/04_1_4_kontrol_za_obrabotkoy_propuschennogo_zvonka/obzor/).
- FinTablo documents importing CRM deals and mapping fields. This is a separate product, FinTablo Connector, not a Context4 feature. [FinTablo guide](https://help.fintablo.ru/article/30329).
- Linear documents creating issues from Sentry errors and linking them. This is the providers' native integration. [Linear documentation](https://linear.app/docs/sentry).

## Before running a workflow

Connect both services and check the tools available in your account. All connectors mentioned here are listed in the public Context4 catalog as **beta**. An action's presence in the catalog does not guarantee access through a particular connection.

The sequences below specify **action keys**, such as `crm.lead.get`. These are not universal MCP tool names: the agent must choose the relevant connection, find the action and read its current input schema. The same key in different services identifies different tools.

For recurring work, your agent or application needs a schedule or external trigger, mapping storage and a log of completed steps. The workflows below do not create those facilities. Store record IDs together with connection IDs: identical numbers in different accounts do not identify the same entity.

Make changes, send messages and place calls only within an explicitly agreed task. If the user has not authorized a specific action or automation rule, show the read results and proposed changes before executing. Do not assume Context4 guarantees a separate confirmation dialog in every AI client.

## 1. Remind a customer of the next step: amoCRM + Wazzup

**Business task.** A customer has reached an agreed deal stage, but the manager must separately find the phone number and a suitable message template.

**Data from two systems.** amoCRM supplies the deal, linked contact and phone number. Wazzup supplies available channels, their state and templates with permitted channels. The agent chooses a message for the deal stage and checks that the selected channel can send it.

### Agent sequence

1. In amoCRM, run `crm.lead.get` for the selected deal. Retrieve the linked contact with `crm.contact.get`. If no contact ID is returned, use a previously verified mapping or ask for it; do not choose a person by name alone.
2. In Wazzup, run `messaging.channel.list` and `messaging.template.list`. Use the returned data to choose a working channel and suitable template, checking its status and channel list.
3. Map the contact's phone number to `chatId`. For this connector, `chatId` is an international phone number containing digits only; an amoCRM contact ID is not valid here. Store the mapping “amoCRM connection + contact ID → Wazzup connection + channelId + chatId”.
4. Prepare the text using deal fields. Show the recipient, channel, template and substituted values. After approval, run `messaging.message.send_template`: take `templateId` from the selected template's `templateGuid`, and values from the agreed data.
5. Store the returned `messageId` and operation state. `accepted` means the request was accepted, not that delivery or reading was confirmed.

**Duplicate prevention.** Before sending, check the log key “connection + deal + stage/reason + template version”. Lock concurrent processing of that key. Do not treat `crmMessageId` as proof of guaranteed deduplication. If sending succeeds but saving the result fails, check the operation and Wazzup first; do not automatically resend when the outcome is unknown.

**Expected result.** An approved message for the intended deal is sent through a checked channel without manually copying the number. The current Wazzup action set cannot read conversation history or delivery status: this workflow cannot establish that the customer has not replied for a long time or has read the message. Check channel rules and template availability separately.

**Task for the agent:** “Prepare a Wazzup reminder for this amoCRM deal. Read the contact, channels and templates. Show the number, template and values; send after my approval. Stop if the previous send's outcome is unknown.”

## 2. Prepare payment follow-up: amoCRM + FinTablo

**Business task.** The manager sees the sale amount in the CRM but needs to check recorded payments and obligations before a conversation.

**Data from two systems.** amoCRM supplies the deal, contact and owner. FinTablo supplies the linked financial deal, obligations and transactions. The result is a set of payment questions linked to the sale's owner.

### Agent sequence

1. In amoCRM, run `crm.lead.get`, then `crm.company.get` or `crm.contact.get` for the linked party if its ID is known.
2. Find the verified mapping “amoCRM connection + deal ID → FinTablo connection + deal ID”, plus the counterparty mapping. During initial setup, read `deal.list` and `partner.list` in FinTablo and propose candidates to a person. Identical company names are insufficient; compare registration details where available and store confirmed IDs.
3. In FinTablo, call `deal.get`, `obligation.list` and `transaction.list` for the financial deal. Separate planned and actual transactions by `isPlan`, accounting for direction, currency, period and every response page.
4. Prepare a summary: CRM deal amount, financial deal data, unpaid obligations and actual receipts for the chosen period. Do not add obligations and transactions as independent debts: they may refer to the same payment. Flag amount differences for reconciliation; do not correct them automatically.
5. In amoCRM, check `crm.task.list`. After approval, use `crm.task.create` to assign the owner a task to check a specific discrepancy or contact the customer. Agree the deadline and task type; verify the result using `crm.task.get`.

**Duplicate prevention.** Use the log key “CRM deal + financial deal + reconciliation period + task type”. Store the created task ID; before retrying, read that task and the task list. If reading FinTablo stops partway through pagination, finish reading before drawing conclusions. If task creation succeeds but the response is lost, find the task before deciding whether to retry.

**Expected result.** The manager receives conversation preparation based on two systems and a concrete task. This is not a real-time bank statement or proof of an overdue payment: import freshness, contract terms, refunds, taxes and currency differences need separate consideration. The workflow does not alter financial records or declare a sale paid merely because amounts match.

**Task for the agent:** “Reconcile this amoCRM deal with the confirmed FinTablo deal for the specified period. Separate planned payments from actual payments. Show discrepancies and suggest a task for the manager without changing financial records.”

## 3. Follow up a missed call: Bitrix24 + MANGO OFFICE

**Business task.** Telephony contains a missed call, and the supervisor needs to know which existing customers have no next step.

**Data from two systems.** MANGO OFFICE returns call records, numbers and answer times. Bitrix24 supplies the contact, deals, owner and existing tasks. The agent checks the call in the context of customer work.

### Agent sequence

1. In MANGO OFFICE, run `telephony.history.request` for an agreed period of at most 28 days. Save the `key`. Retrieve the report through `telephony.history.result`, respecting `pollAfterMs`; `pending` does not mean there were no calls.
2. Identify unanswered inbound calls in the completed report according to the provider's field rules. Do not treat every termination code as a missed call; account for subsequent answered calls from the same customer within the period. Store `entry_id` and the numbers.
3. In Bitrix24, find the contact through `crm.contact.list`, then read `crm.contact.get` and linked deals through `crm.deal.list` / `crm.deal.get`. Match the normalized external number, then store the contact ID. If a number is shared or multiple contacts match, ask a person to choose.
4. Use `task.task.list` to check whether a task already exists for this call. Show the contact, deal, call time, owner and proposed deadline. After approval, run `task.task.create`, including a customer link and the call's `entry_id` in the description.
5. Verify the task with `task.task.get` and save its ID. If the user has separately authorized an actual call, first read `telephony.employee.list` and agree the employee and `extension`, then use `telephony.call.callback` with the exact customer number and `command_id`.

**Duplicate prevention.** For a task, use the key “MANGO connection + entry_id + next-step type”. Keep a separate attempt record for a call: an accepted request must not be automatically repeated like a read. If the response is lost, check the operation and telephony. If the report expires (`absent-or-expired`), request the same period again and exclude processed `entry_id` values.

**Expected result.** Known missed inquiries receive a verifiable next step and an owner. A created task does not mean the customer was called back; `submitted` for a callback means the command was sent, not that a conversation occurred. Check report completeness: a limited response does not establish that there were no other calls. An existing native integration may create tasks independently; account for it to avoid duplicate work.

**Task for the agent:** “Match MANGO OFFICE missed inbound calls in this period to Bitrix24 contacts, deals and tasks. Show inquiries without a next step. Do not create tasks or place calls until the list is approved.”

## 4. Assign an error without duplicates: Sentry + Linear

**Business task.** An error is visible in monitoring, but before creating an issue you need to find out whether the development team is already handling it.

**Data from two systems.** Sentry supplies the error ID, events, frequency and failure context within its response. Linear supplies existing issues, their state, team and discussion. The agent combines technical error evidence with current work plans.

### Agent sequence

1. In Sentry, run `issue.triage_pack` for the selected error. Save the organization, project, numeric ID and issue URL. Do not copy secrets or unnecessary event personal data into the issue.
2. In Linear, run `issue.search` using the saved Sentry ID/URL and key error characteristics. Use `issue.overview` for candidates to read issues and comments. Matching titles alone do not confirm a shared cause.
3. If a mapping is already confirmed, show an update for the existing issue. After approval, add it with `comment.create`. If no issue exists, run `team.list`, agree the team and content, then call `issue.create`.
4. Include the Sentry URL, observed facts and observation period in the description or comment. Separate facts from hypotheses. Store the mapping “Sentry organization + error ID → Linear workspace + issue ID”.
5. Verify the result through `issue.get` or `comment.list` in Linear. Show the user the URL of the created or updated issue.

**Duplicate prevention.** Before writing, lock the log key “Sentry organization + error ID + Linear team”. For comments, add the period or last processed event ID. If creation succeeds but updating the log fails, search by the Sentry URL first. Do not automatically create a second issue when the outcome is unknown.

**Expected result.** The team receives an issue with context from a real failure or an update to an existing issue. Adding a text link does not enable the native two-way Linear–Sentry integration. These steps do not promise automatic Sentry closure when Linear work completes and do not establish a root cause without further investigation.

**Task for the agent:** “Read this Sentry error and find its linked Linear issue. Show what both systems already know. Suggest a comment or a new issue, separate facts from hypotheses and wait for approval before writing.”

## How to verify the first run

Start with one known record. Check that the agent read data from **both** services, showed the matching method and reported ambiguities. After an authorized write, open the result in the original service. A repeated run should find the completed step; a failure in the second service should leave a clear state for resuming.

Next, read about [connecting services](https://ctx4.me/docs/connections.md), [actions and results](https://ctx4.me/docs/actions.md) and [working through AI and MCP](https://ctx4.me/docs/ai-mcp.md).

---

# Executions

Source: https://ctx4.me/docs/api-executions

Generated from the public Context4 OpenAPI. Authenticate with `Authorization: Bearer` and an API key. General rules: [API](https://ctx4.me/docs/api.md). Full contract: [OpenAPI JSON](https://ctx4.me/docs/openapi.json). In the JSON below, `$ref` points to a named schema in the Schemas section.

## createExecution

`POST /v1/executions`

Deployment URL: `https://ctx4.me/v1/executions`. Replace parameters in braces with actual IDs from the API.

Create an execution (asynchronous, idempotent)

Capability: `executions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | &#123;"type":"string"&#125; Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome |

### Request body

Required. [CreateExecutionRequest](https://ctx4.me/docs/api-schemas-1.md#createexecutionrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateExecutionRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 202 | Execution accepted (queued) or persisted as rejected with a denial code; poll the Location header | `application/json` [Execution](https://ctx4.me/docs/api-schemas-1.md#execution) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden, session_expired, session_revoked, session_call_budget_exhausted) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (idempotency_conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  },
  "Location": {
    "description": "Resource location (/v1/executions/{executionId})",
    "schema": {
      "type": "string"
    }
  }
}
```

## listExecutions

`GET /v1/executions`

Deployment URL: `https://ctx4.me/v1/executions`. Replace parameters in braces with actual IDs from the API.

List executions

Capability: `executions:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `status` | query | no | &#123;"type":"string","enum":["requested","queued","running","retrying","succeeded","failed","rejected","cancelled"]&#125;  |
| `connector_id` | query | no | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `user_id` | query | no | &#123;"$ref":"#/components/schemas/ExecutionEndUserRef"&#125;  |
| `from` | query | no | &#123;"type":"string","format":"date-time","example":"2026-07-16T12:00:00.000Z"&#125;  |
| `to` | query | no | &#123;"type":"string","format":"date-time","example":"2026-07-16T12:00:00.000Z"&#125;  |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"&#125; Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Executions ordered by creation time (descending) | `application/json` [ExecutionListResponse](https://ctx4.me/docs/api-schemas-1.md#executionlistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getExecution

`GET /v1/executions/{executionId}`

Deployment URL: `https://ctx4.me/v1/executions/{executionId}`. Replace parameters in braces with actual IDs from the API.

Get one execution with its result

Capability: `executions:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `executionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Execution view; terminal successes include the result | `application/json` [ExecutionWithResult](https://ctx4.me/docs/api-schemas-1.md#executionwithresult) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listExecutionAttempts

`GET /v1/executions/{executionId}/attempts`

Deployment URL: `https://ctx4.me/v1/executions/{executionId}/attempts`. Replace parameters in braces with actual IDs from the API.

List execution attempts

Capability: `executions:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `executionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Append-only attempt records | `application/json` [AttemptListResponse](https://ctx4.me/docs/api-schemas-1.md#attemptlistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## cancelExecution

`POST /v1/executions/{executionId}/cancel`

Deployment URL: `https://ctx4.me/v1/executions/{executionId}/cancel`. Replace parameters in braces with actual IDs from the API.

Cancel a queued execution

Capability: `executions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `executionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Request body

Required. [CancelExecutionRequest](https://ctx4.me/docs/api-schemas-1.md#cancelexecutionrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CancelExecutionRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The cancelled execution | `application/json` [Execution](https://ctx4.me/docs/api-schemas-1.md#execution) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict, execution_not_cancellable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

---

# Connections and OAuth applications

Source: https://ctx4.me/docs/api-connections

Generated from the public Context4 OpenAPI. Authenticate with `Authorization: Bearer` and an API key. General rules: [API](https://ctx4.me/docs/api.md). Full contract: [OpenAPI JSON](https://ctx4.me/docs/openapi.json). In the JSON below, `$ref` points to a named schema in the Schemas section.

## listConnections

`GET /v1/connections`

Deployment URL: `https://ctx4.me/v1/connections`. Replace parameters in braces with actual IDs from the API.

List connections

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `status` | query | no | &#123;"type":"string","enum":["pending","active","degraded","revoked","failed"]&#125;  |
| `user_id` | query | no | &#123;"$ref":"#/components/schemas/EndUserRef"&#125;  |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"&#125; Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Connections in the key's workspace | `application/json` [ConnectionListResponse](https://ctx4.me/docs/api-schemas-1.md#connectionlistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## createConnection

`POST /v1/connections`

Deployment URL: `https://ctx4.me/v1/connections`. Replace parameters in braces with actual IDs from the API.

Initiate a connection (hosted auth link)

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | &#123;"type":"string"&#125; Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome |

### Request body

Required. [CreateConnectionRequest](https://ctx4.me/docs/api-schemas-2.md#createconnectionrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateConnectionRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 201 | Hosted authorization link for the end user | `application/json` [HostedAuthLink](https://ctx4.me/docs/api-schemas-2.md#hostedauthlink) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getConnection

`GET /v1/connections/{connectionId}`

Deployment URL: `https://ctx4.me/v1/connections/{connectionId}`. Replace parameters in braces with actual IDs from the API.

Get one connection

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Connection view (engine-free) | `application/json` [Connection](https://ctx4.me/docs/api-schemas-1.md#connection) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listAuthConfigs

`GET /v1/auth-configs`

Deployment URL: `https://ctx4.me/v1/auth-configs`. Replace parameters in braces with actual IDs from the API.

List auth configurations

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connector_id` | query | no | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"&#125; Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Auth configurations in the key's workspace | `application/json` [AuthConfigListResponse](https://ctx4.me/docs/api-schemas-2.md#authconfiglistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## createAuthConfig

`POST /v1/auth-configs`

Deployment URL: `https://ctx4.me/v1/auth-configs`. Replace parameters in braces with actual IDs from the API.

Create an auth configuration

Capability: `connections:write`.

The contract defines no additional parameters.

### Request body

Required. [CreateAuthConfigRequest](https://ctx4.me/docs/api-schemas-2.md#createauthconfigrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateAuthConfigRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 201 | The created auth configuration | `application/json` [AuthConfig](https://ctx4.me/docs/api-schemas-2.md#authconfig) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getAuthConfig

`GET /v1/auth-configs/{authConfigId}`

Deployment URL: `https://ctx4.me/v1/auth-configs/{authConfigId}`. Replace parameters in braces with actual IDs from the API.

Get one auth configuration

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `authConfigId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Auth configuration (secret-free) | `application/json` [AuthConfig](https://ctx4.me/docs/api-schemas-2.md#authconfig) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## updateAuthConfig

`PATCH /v1/auth-configs/{authConfigId}`

Deployment URL: `https://ctx4.me/v1/auth-configs/{authConfigId}`. Replace parameters in braces with actual IDs from the API.

Update an auth configuration

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `authConfigId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Request body

Required. [UpdateAuthConfigRequest](https://ctx4.me/docs/api-schemas-2.md#updateauthconfigrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UpdateAuthConfigRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The updated auth configuration | `application/json` [AuthConfig](https://ctx4.me/docs/api-schemas-2.md#authconfig) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## deleteAuthConfig

`DELETE /v1/auth-configs/{authConfigId}`

Deployment URL: `https://ctx4.me/v1/auth-configs/{authConfigId}`. Replace parameters in braces with actual IDs from the API.

Delete an auth configuration

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `authConfigId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 204 | Deleted | The contract does not define a body |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getProviderSchema

`GET /v1/connections/{connectionId}/schemas/{entity}`

Deployment URL: `https://ctx4.me/v1/connections/{connectionId}/schemas/{entity}`. Replace parameters in braces with actual IDs from the API.

Read the latest discovered provider entity schema

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |
| `entity` | path | yes | &#123;"type":"string","minLength":1,"maxLength":80&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Latest tenant-scoped provider schema | `application/json` [ProviderSchema](https://ctx4.me/docs/api-schemas-3.md#providerschema) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## discoverProviderSchema

`POST /v1/connections/{connectionId}/schemas/{entity}`

Deployment URL: `https://ctx4.me/v1/connections/{connectionId}/schemas/{entity}`. Replace parameters in braces with actual IDs from the API.

Discover and persist provider entity metadata

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | &#123;"type":"string"&#125; Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome |
| `connectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |
| `entity` | path | yes | &#123;"type":"string","minLength":1,"maxLength":80&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Immutable provider schema revision | `application/json` [ProviderSchema](https://ctx4.me/docs/api-schemas-3.md#providerschema) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

---

# Databases and private networks

Source: https://ctx4.me/docs/api-sources

Generated from the public Context4 OpenAPI. Authenticate with `Authorization: Bearer` and an API key. General rules: [API](https://ctx4.me/docs/api.md). Full contract: [OpenAPI JSON](https://ctx4.me/docs/openapi.json). In the JSON below, `$ref` points to a named schema in the Schemas section.

## setNetworkAttachmentConnectivity

`PATCH /v1/network-attachments/{networkAttachmentId}/connectivity`

Deployment URL: `https://ctx4.me/v1/network-attachments/{networkAttachmentId}/connectivity`. Replace parameters in braces with actual IDs from the API.

Disconnect or reconnect a private-network attachment

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `networkAttachmentId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Request body

Required. 

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "expected_version": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "expected_version",
          "enabled"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Persisted connectivity intent; status reason reports operator acknowledgement | `application/json` [NetworkAttachment](https://ctx4.me/docs/api-schemas-2.md#networkattachment) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listNetworkAttachments

`GET /v1/network-attachments`

Deployment URL: `https://ctx4.me/v1/network-attachments`. Replace parameters in braces with actual IDs from the API.

List private-network attachments

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"&#125; Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Tenant-scoped secret-free attachment views | `application/json` [NetworkAttachmentList](https://ctx4.me/docs/api-schemas-2.md#networkattachmentlist) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## createNetworkAttachment

`POST /v1/network-attachments`

Deployment URL: `https://ctx4.me/v1/network-attachments`. Replace parameters in braces with actual IDs from the API.

Create a typed direct, WireGuard, or OpenVPN attachment

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | &#123;"type":"string"&#125; Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome |

### Request body

Required. [CreateNetworkAttachmentRequest](https://ctx4.me/docs/api-schemas-2.md#createnetworkattachmentrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateNetworkAttachmentRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 201 | Created attachment; private credentials are never returned | `application/json` [NetworkAttachment](https://ctx4.me/docs/api-schemas-2.md#networkattachment) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getNetworkAttachment

`GET /v1/network-attachments/{networkAttachmentId}`

Deployment URL: `https://ctx4.me/v1/network-attachments/{networkAttachmentId}`. Replace parameters in braces with actual IDs from the API.

Get one private-network attachment

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `networkAttachmentId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Secret-free attachment health and desired state | `application/json` [NetworkAttachment](https://ctx4.me/docs/api-schemas-2.md#networkattachment) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## updateNetworkAttachment

`PATCH /v1/network-attachments/{networkAttachmentId}`

Deployment URL: `https://ctx4.me/v1/network-attachments/{networkAttachmentId}`. Replace parameters in braces with actual IDs from the API.

Replace the approved destination policy

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `networkAttachmentId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Request body

Required. 

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "dns_servers": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "ip"
                },
                {
                  "type": "string",
                  "format": "ip"
                }
              ]
            },
            "maxItems": 3
          },
          "expected_version": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "destinations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "host": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 253,
                  "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"
                },
                "port": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 65535
                }
              },
              "required": [
                "host",
                "port"
              ],
              "additionalProperties": false
            },
            "minItems": 1,
            "maxItems": 64
          }
        },
        "required": [
          "expected_version",
          "destinations"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Updated desired generation | `application/json` [NetworkAttachment](https://ctx4.me/docs/api-schemas-2.md#networkattachment) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## revokeNetworkAttachment

`DELETE /v1/network-attachments/{networkAttachmentId}`

Deployment URL: `https://ctx4.me/v1/network-attachments/{networkAttachmentId}`. Replace parameters in braces with actual IDs from the API.

Drain and revoke a private-network attachment

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `networkAttachmentId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |
| `expected_version` | query | yes | &#123;"type":"integer","exclusiveMinimum":0&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Draining or ready-to-revoke attachment | `application/json` [NetworkAttachment](https://ctx4.me/docs/api-schemas-2.md#networkattachment) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## discoverSavedDatabases

`POST /v1/data-source-connections/{dataSourceConnectionId}/discover-databases`

Deployment URL: `https://ctx4.me/v1/data-source-connections/{dataSourceConnectionId}/discover-databases`. Replace parameters in braces with actual IDs from the API.

Discover databases using a stored, tenant-owned connection

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `dataSourceConnectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Bounded database catalog without returning credentials | `application/json` [DiscoverPostgresDatabasesResponse](https://ctx4.me/docs/api-schemas-2.md#discoverpostgresdatabasesresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## addDatabaseFromConnection

`POST /v1/data-source-connections/{dataSourceConnectionId}/databases`

Deployment URL: `https://ctx4.me/v1/data-source-connections/{dataSourceConnectionId}/databases`. Replace parameters in braces with actual IDs from the API.

Add a database using the stored server credential

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | &#123;"type":"string"&#125; Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome |
| `dataSourceConnectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Request body

Required. [AddDatabaseFromConnectionRequest](https://ctx4.me/docs/api-schemas-2.md#adddatabasefromconnectionrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AddDatabaseFromConnectionRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 201 | Independent database connection with its own revocable secret | `application/json` [DataSourceConnection](https://ctx4.me/docs/api-schemas-2.md#datasourceconnection) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## discoverPostgresDatabases

`POST /v1/data-source-connections/discover-databases`

Deployment URL: `https://ctx4.me/v1/data-source-connections/discover-databases`. Replace parameters in braces with actual IDs from the API.

Discover PostgreSQL or SQL Server databases before creating a source

Capability: `connections:write`.

The contract defines no additional parameters.

### Request body

Required. [DiscoverPostgresDatabasesRequest](https://ctx4.me/docs/api-schemas-2.md#discoverpostgresdatabasesrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/DiscoverPostgresDatabasesRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Bounded database catalog with explicit session evidence | `application/json` [DiscoverPostgresDatabasesResponse](https://ctx4.me/docs/api-schemas-2.md#discoverpostgresdatabasesresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listDataSourceConnections

`GET /v1/data-source-connections`

Deployment URL: `https://ctx4.me/v1/data-source-connections`. Replace parameters in braces with actual IDs from the API.

List database and topic source connections

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"&#125; Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Tenant-scoped secret-free source views | `application/json` [DataSourceConnectionList](https://ctx4.me/docs/api-schemas-2.md#datasourceconnectionlist) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## createDataSourceConnection

`POST /v1/data-source-connections`

Deployment URL: `https://ctx4.me/v1/data-source-connections`. Replace parameters in braces with actual IDs from the API.

Create a typed database or topic source connection

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | &#123;"type":"string"&#125; Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome |

### Request body

Required. [CreateDataSourceConnectionRequest](https://ctx4.me/docs/api-schemas-3.md#createdatasourceconnectionrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateDataSourceConnectionRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 201 | Created source; credentials are never returned | `application/json` [DataSourceConnection](https://ctx4.me/docs/api-schemas-2.md#datasourceconnection) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getDataSourceConnection

`GET /v1/data-source-connections/{dataSourceConnectionId}`

Deployment URL: `https://ctx4.me/v1/data-source-connections/{dataSourceConnectionId}`. Replace parameters in braces with actual IDs from the API.

Get one database or topic source connection

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `dataSourceConnectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Secret-free source connection view | `application/json` [DataSourceConnection](https://ctx4.me/docs/api-schemas-2.md#datasourceconnection) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## revokeDataSourceConnection

`DELETE /v1/data-source-connections/{dataSourceConnectionId}`

Deployment URL: `https://ctx4.me/v1/data-source-connections/{dataSourceConnectionId}`. Replace parameters in braces with actual IDs from the API.

Revoke a database or topic source connection

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `dataSourceConnectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Revoked source connection | `application/json` [DataSourceConnection](https://ctx4.me/docs/api-schemas-2.md#datasourceconnection) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## replaceDataSourceCredential

`POST /v1/data-source-connections/{dataSourceConnectionId}/credential`

Deployment URL: `https://ctx4.me/v1/data-source-connections/{dataSourceConnectionId}/credential`. Replace parameters in braces with actual IDs from the API.

Replace the password credential of a source connection

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `dataSourceConnectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Request body

Required. [ReplaceDataSourceCredentialRequest](https://ctx4.me/docs/api-schemas-3.md#replacedatasourcecredentialrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReplaceDataSourceCredentialRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Source with the new credential version; a degraded source returns to pending until an inspection succeeds | `application/json` [DataSourceConnection](https://ctx4.me/docs/api-schemas-2.md#datasourceconnection) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getDataSourceSchema

`GET /v1/data-source-connections/{dataSourceConnectionId}/schema`

Deployment URL: `https://ctx4.me/v1/data-source-connections/{dataSourceConnectionId}/schema`. Replace parameters in braces with actual IDs from the API.

Get the latest discovered source schema

Capability: `connections:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `dataSourceConnectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Latest tenant-scoped source schema | `application/json` [SourceSchema](https://ctx4.me/docs/api-schemas-3.md#sourceschema) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## discoverDataSourceSchema

`POST /v1/data-source-connections/{dataSourceConnectionId}/schema`

Deployment URL: `https://ctx4.me/v1/data-source-connections/{dataSourceConnectionId}/schema`. Replace parameters in braces with actual IDs from the API.

Inspect a source, persist its schema, and activate the connection

Capability: `connections:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | &#123;"type":"string"&#125; Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome |
| `dataSourceConnectionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Discovered immutable source schema version | `application/json` [SourceSchema](https://ctx4.me/docs/api-schemas-3.md#sourceschema) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

---

# Tool sessions

Source: https://ctx4.me/docs/api-sessions

Generated from the public Context4 OpenAPI. Authenticate with `Authorization: Bearer` and an API key. General rules: [API](https://ctx4.me/docs/api.md). Full contract: [OpenAPI JSON](https://ctx4.me/docs/openapi.json). In the JSON below, `$ref` points to a named schema in the Schemas section.

## createToolSession

`POST /v1/tool-sessions`

Deployment URL: `https://ctx4.me/v1/tool-sessions`. Replace parameters in braces with actual IDs from the API.

Create a tool session (returns the per-session MCP URL)

Capability: `tool-sessions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | &#123;"type":"string"&#125; Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome |

### Request body

Required. [CreateToolSessionRequest](https://ctx4.me/docs/api-schemas-3.md#createtoolsessionrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateToolSessionRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 201 | The created session with its per-session MCP URL | `application/json` [ToolSessionWithMcp](https://ctx4.me/docs/api-schemas-3.md#toolsessionwithmcp) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getToolSession

`GET /v1/tool-sessions/{toolSessionId}`

Deployment URL: `https://ctx4.me/v1/tool-sessions/{toolSessionId}`. Replace parameters in braces with actual IDs from the API.

Get one tool session with its configuration

Capability: `tool-sessions:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `toolSessionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The session view including its configuration | `application/json` [ToolSession](https://ctx4.me/docs/api-schemas-3.md#toolsession) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## patchToolSession

`PATCH /v1/tool-sessions/{toolSessionId}`

Deployment URL: `https://ctx4.me/v1/tool-sessions/{toolSessionId}`. Replace parameters in braces with actual IDs from the API.

Update session tool enablement (CAS)

Capability: `tool-sessions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `toolSessionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Request body

Required. [PatchToolSessionRequest](https://ctx4.me/docs/api-schemas-3.md#patchtoolsessionrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PatchToolSessionRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The updated session view | `application/json` [ToolSession](https://ctx4.me/docs/api-schemas-3.md#toolsession) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listToolSessionTools

`GET /v1/tool-sessions/{toolSessionId}/tools`

Deployment URL: `https://ctx4.me/v1/tool-sessions/{toolSessionId}/tools`. Replace parameters in braces with actual IDs from the API.

Session-scoped tool discovery (pinned snapshot, exposed tools only)

Capability: `tool-sessions:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `toolSessionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"&#125; Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The session's exposed tools with pinned schemas | `application/json` [SessionToolListResponse](https://ctx4.me/docs/api-schemas-3.md#sessiontoollistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

---

# Sync and export

Source: https://ctx4.me/docs/api-syncs

Generated from the public Context4 OpenAPI. Authenticate with `Authorization: Bearer` and an API key. General rules: [API](https://ctx4.me/docs/api.md). Full contract: [OpenAPI JSON](https://ctx4.me/docs/openapi.json). In the JSON below, `$ref` points to a named schema in the Schemas section.

## getSyncDeliveryAuthority

`GET /v1/syncs/{syncId}/delivery-authority`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}/delivery-authority`. Replace parameters in braces with actual IDs from the API.

Read the tenant-scoped delivery grant fence for a sync resource

Capability: `syncs:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |
| `entity` | query | yes | &#123;"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]&#123;0,79&#125;$"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Persisted delivery grants and source lineage without credentials | `application/json` [SyncDeliveryAuthority](https://ctx4.me/docs/api-schemas-3.md#syncdeliveryauthority) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## createSync

`POST /v1/syncs`

Deployment URL: `https://ctx4.me/v1/syncs`. Replace parameters in braces with actual IDs from the API.

Create a sync binding a connection to a syncable entity

Capability: `syncs:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | no | &#123;"type":"string"&#125; Required when source_kind is database_poll; retries with the same key and payload return the original sync. Optional for other source kinds. |

### Request body

Required. 

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "connection_id": {
            "type": "string",
            "format": "uuid",
            "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
          },
          "source_kind": {
            "type": "string",
            "enum": [
              "api_poll",
              "database_cdc",
              "database_poll",
              "topic"
            ]
          },
          "database_poll": {
            "type": "object",
            "properties": {
              "schema": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "table": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "columns": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "minItems": 1,
                "maxItems": 256
              },
              "primary_key": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "minItems": 1,
                "maxItems": 16
              },
              "mode": {
                "type": "string",
                "enum": [
                  "full_scan",
                  "rowversion",
                  "timestamp"
                ]
              },
              "watermark_column": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 1,
                "maxLength": 128
              },
              "full_reconciliation_minutes": {
                "type": "integer",
                "minimum": 1,
                "maximum": 10080
              },
              "timestamp_overlap_seconds": {
                "type": "integer",
                "minimum": 0,
                "maximum": 86400
              },
              "deletion_policy": {
                "type": "string",
                "enum": [
                  "preserve",
                  "confirm_missing"
                ]
              }
            },
            "required": [
              "schema",
              "table",
              "columns",
              "primary_key"
            ],
            "additionalProperties": false
          },
          "entity": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$"
          },
          "schedule_minutes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10080
          }
        },
        "required": [
          "connection_id",
          "entity"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 201 | The created sync; acquisition and initial loading follow the provider capabilities | `application/json` [Sync](https://ctx4.me/docs/api-schemas-3.md#sync) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited, quota_exceeded) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listSyncs

`GET /v1/syncs`

Deployment URL: `https://ctx4.me/v1/syncs`. Replace parameters in braces with actual IDs from the API.

List syncs in the workspace

Capability: `syncs:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 25)"&#125; Page size (1-100, default 25) |
| `connection_id` | query | no | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | One page of syncs with the continuation cursor | `application/json` [SyncList](https://ctx4.me/docs/api-schemas-3.md#synclist) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getSync

`GET /v1/syncs/{syncId}`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}`. Replace parameters in braces with actual IDs from the API.

Get one sync

Capability: `syncs:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The sync view | `application/json` [Sync](https://ctx4.me/docs/api-schemas-3.md#sync) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## patchSync

`PATCH /v1/syncs/{syncId}`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}`. Replace parameters in braces with actual IDs from the API.

Pause, resume, or update the schedule of a sync

Capability: `syncs:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Request body

Required. 

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "pause",
                  "resume"
                ]
              }
            },
            "required": [
              "action"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "update_schedule"
                ]
              },
              "schedule_minutes": {
                "type": "integer",
                "minimum": 1,
                "maximum": 10080
              },
              "full_reconciliation_minutes": {
                "type": "integer",
                "minimum": 1,
                "maximum": 10080
              },
              "deletion_policy": {
                "type": "string",
                "enum": [
                  "preserve"
                ]
              },
              "expected_config_revision": {
                "type": "integer",
                "exclusiveMinimum": 0
              }
            },
            "required": [
              "action",
              "schedule_minutes",
              "expected_config_revision"
            ],
            "additionalProperties": false
          }
        ]
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The updated sync view | `application/json` [Sync](https://ctx4.me/docs/api-schemas-3.md#sync) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## deleteSync

`DELETE /v1/syncs/{syncId}`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}`. Replace parameters in braces with actual IDs from the API.

Delete a sync (record history stays pullable)

Capability: `syncs:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The deleted sync view | `application/json` [Sync](https://ctx4.me/docs/api-schemas-3.md#sync) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## testFireSync

`POST /v1/syncs/test-fire`

Deployment URL: `https://ctx4.me/v1/syncs/test-fire`. Replace parameters in braces with actual IDs from the API.

Synchronously probe a bounded record sample without persisting anything

Capability: `syncs:write`.

The contract defines no additional parameters.

### Request body

Required. 

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "connection_id": {
            "type": "string",
            "format": "uuid",
            "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
          },
          "entity": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$"
          },
          "sample_limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          }
        },
        "required": [
          "connection_id",
          "entity"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Normalized sample records plus the estimated total volume | `application/json` [SyncTestFire](https://ctx4.me/docs/api-schemas-3.md#synctestfire) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable, provider_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## triggerSyncRun

`POST /v1/syncs/{syncId}/trigger`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}/trigger`. Replace parameters in braces with actual IDs from the API.

Enqueue a manual run

Capability: `syncs:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | no | &#123;"type":"string"&#125; Required when the sync source_kind is database_poll; retries with the same key return the original run. Optional for other source kinds. |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 202 | The sync view with the planned run enqueued | `application/json` [Sync](https://ctx4.me/docs/api-schemas-3.md#sync) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict). The source does not support a manual refresh, or a run is already active | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listSyncRuns

`GET /v1/syncs/{syncId}/runs`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}/runs`. Replace parameters in braces with actual IDs from the API.

Run history with per-change-type counters and error causes

Capability: `syncs:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 25)"&#125; Page size (1-100, default 25) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | One page of runs with the continuation cursor | `application/json` [SyncRunList](https://ctx4.me/docs/api-schemas-3.md#syncrunlist) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## pullSyncRecords

`GET /v1/syncs/{syncId}/records`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}/records`. Replace parameters in braces with actual IDs from the API.

Cursor-paged record change stream (the pull door onto the broker stream)

Capability: `syncs:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 25)"&#125; Page size (1-100, default 25) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | One page of record changes ordered by modification cursor | `application/json` [SyncRecordList](https://ctx4.me/docs/api-schemas-4.md#syncrecordlist) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## replaySyncRecords

`POST /v1/syncs/{syncId}/replay`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}/replay`. Replace parameters in braces with actual IDs from the API.

Replay dead-lettered record deliveries for a sync

Capability: `syncs:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The number of records reset for republication | `application/json` [SyncReplay](https://ctx4.me/docs/api-schemas-4.md#syncreplay) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listSyncableEntities

`GET /v1/connectors/{connectorId}/syncable-entities`

Deployment URL: `https://ctx4.me/v1/connectors/{connectorId}/syncable-entities`. Replace parameters in braces with actual IDs from the API.

Entities the catalog declares syncable for a connector

Capability: `syncs:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectorId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Syncable entities with strategy and default schedule | `application/json` [SyncableEntityList](https://ctx4.me/docs/api-schemas-4.md#syncableentitylist) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getSyncDeliveryCapabilities

`GET /v1/sync-delivery-capabilities`

Deployment URL: `https://ctx4.me/v1/sync-delivery-capabilities`. Replace parameters in braces with actual IDs from the API.

Delivery limits and semantics a consumer must satisfy

Capability: `syncs:read`.

The contract defines no additional parameters.

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Byte limits, envelope versions and delete semantics this deployment honours | `application/json` [SyncDeliveryCapabilities](https://ctx4.me/docs/api-schemas-4.md#syncdeliverycapabilities) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## createSyncExport

`POST /v1/syncs/{syncId}/exports`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}/exports`. Replace parameters in braces with actual IDs from the API.

Open an immutable historical export over a captured frontier

Capability: `syncs:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Request body

Required. 

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "destination": {
            "type": "string",
            "enum": [
              "file",
              "bounded-replay-topic"
            ]
          },
          "entity": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$"
          },
          "idempotency_key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "range": {
            "type": "object",
            "properties": {
              "after_cursor": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]{0,18})$"
              },
              "through_cursor": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^(0|[1-9][0-9]{0,18})$"
              }
            },
            "required": [
              "after_cursor",
              "through_cursor"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "entity",
          "idempotency_key"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 201 | Export session with its captured frontier and publication barrier | `application/json` [SyncExportSession](https://ctx4.me/docs/api-schemas-4.md#syncexportsession) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable, provider_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## cancelSyncExport

`POST /v1/syncs/{syncId}/exports/{exportId}/cancel`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}/exports/{exportId}/cancel`. Replace parameters in braces with actual IDs from the API.

Request cancellation of a running export

Capability: `syncs:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |
| `exportId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 202 | Cancellation recorded; the session reaches `cancelled` once the runner stops | `application/json` [SyncExportSession](https://ctx4.me/docs/api-schemas-4.md#syncexportsession) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getSyncExport

`GET /v1/syncs/{syncId}/exports/{exportId}`

Deployment URL: `https://ctx4.me/v1/syncs/{syncId}/exports/{exportId}`. Replace parameters in braces with actual IDs from the API.

Read an export session's state and progress

Capability: `syncs:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `syncId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |
| `exportId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Export session state, progress and terminal outcome | `application/json` [SyncExportSession](https://ctx4.me/docs/api-schemas-4.md#syncexportsession) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listSyncProviders

`GET /v1/sync-providers`

Deployment URL: `https://ctx4.me/v1/sync-providers`. Replace parameters in braces with actual IDs from the API.

List published Sync providers

Capability: `syncs:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"&#125; Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Published providers with Sync entities; empty pages may have a continuation cursor | `application/json` [SyncProviderListResponse](https://ctx4.me/docs/api-schemas-4.md#syncproviderlistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

---

# Provider events

Source: https://ctx4.me/docs/api-events

Generated from the public Context4 OpenAPI. Authenticate with `Authorization: Bearer` and an API key. General rules: [API](https://ctx4.me/docs/api.md). Full contract: [OpenAPI JSON](https://ctx4.me/docs/openapi.json). In the JSON below, `$ref` points to a named schema in the Schemas section.

## listProviderEventTypes

`GET /v1/provider-event-types`

Deployment URL: `https://ctx4.me/v1/provider-event-types`. Replace parameters in braces with actual IDs from the API.

List supported provider notification types and fields

Capability: `events:read`.

The contract defines no additional parameters.

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Provider event catalog | `application/json` &#123;"type":"object","properties":&#123;"data":&#123;"type":"array","items":&#123;"type":"object","properties":&#123;"connector_id":&#123;"type":"string"&#125;,"entity":&#123;"type":"string"&#125;,"event_types":&#123;"type":"array","items":&#123;"type":"string"&#125;&#125;,"fields":&#123;"type":"array","items":&#123;"type":"string"&#125;&#125;,"field_types":&#123;"type":"object","additionalProperties":&#123;"type":"string","enum":["string","number","boolean"]&#125;&#125;,"hydration_available":&#123;"type":"boolean"&#125;&#125;,"required":["connector_id","entity","event_types","fields","field_types","hydration_available"],"additionalProperties":false&#125;&#125;&#125;,"required":["data"],"additionalProperties":false&#125; |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## subscribeProviderEvents

`POST /v1/provider-event-subscriptions`

Deployment URL: `https://ctx4.me/v1/provider-event-subscriptions`. Replace parameters in braces with actual IDs from the API.

Subscribe to provider events without entity storage

Capability: `events:write`.

The contract defines no additional parameters.

### Request body

Required. 

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "connection_id": {
            "type": "string",
            "format": "uuid",
            "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
          },
          "event_types": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 160
            },
            "minItems": 1,
            "maxItems": 32
          }
        },
        "required": [
          "connection_id",
          "event_types"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Configured event subscription | `application/json` &#123;"type":"object","properties":&#123;"id":&#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;,"connection_id":&#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;,"source_id":&#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;,"connector_id":&#123;"type":"string"&#125;,"event_types":&#123;"type":"array","items":&#123;"type":"string"&#125;&#125;,"status":&#123;"type":"string"&#125;,"version":&#123;"type":"integer","exclusiveMinimum":0&#125;,"enabled_at":&#123;"type":"string","format":"date-time"&#125;,"payload_retention_seconds":&#123;"type":"integer","exclusiveMinimum":0&#125;&#125;,"required":["id","connection_id","source_id","connector_id","event_types","status","version","enabled_at","payload_retention_seconds"],"additionalProperties":false&#125; |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getProviderEventSubscription

`GET /v1/provider-event-subscriptions`

Deployment URL: `https://ctx4.me/v1/provider-event-subscriptions`. Replace parameters in braces with actual IDs from the API.

Read the connection event subscription

Capability: `events:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connection_id` | query | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Subscription or null | `application/json` &#123;"type":["object","null"],"properties":&#123;"id":&#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;,"connection_id":&#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;,"source_id":&#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;,"connector_id":&#123;"type":"string"&#125;,"event_types":&#123;"type":"array","items":&#123;"type":"string"&#125;&#125;,"status":&#123;"type":"string"&#125;,"version":&#123;"type":"integer","exclusiveMinimum":0&#125;,"enabled_at":&#123;"type":"string","format":"date-time"&#125;,"payload_retention_seconds":&#123;"type":"integer","exclusiveMinimum":0&#125;&#125;,"required":["id","connection_id","source_id","connector_id","event_types","status","version","enabled_at","payload_retention_seconds"],"additionalProperties":false&#125; |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## disableProviderEventSubscription

`DELETE /v1/provider-event-subscriptions/{subscriptionId}`

Deployment URL: `https://ctx4.me/v1/provider-event-subscriptions/{subscriptionId}`. Replace parameters in braces with actual IDs from the API.

Disable a provider event subscription

Capability: `events:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `subscriptionId` | path | yes | &#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Disabled subscription | `application/json` &#123;"type":"object","properties":&#123;"id":&#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;,"connection_id":&#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;,"source_id":&#123;"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"&#125;,"connector_id":&#123;"type":"string"&#125;,"event_types":&#123;"type":"array","items":&#123;"type":"string"&#125;&#125;,"status":&#123;"type":"string"&#125;,"version":&#123;"type":"integer","exclusiveMinimum":0&#125;,"enabled_at":&#123;"type":"string","format":"date-time"&#125;,"payload_retention_seconds":&#123;"type":"integer","exclusiveMinimum":0&#125;&#125;,"required":["id","connection_id","source_id","connector_id","event_types","status","version","enabled_at","payload_retention_seconds"],"additionalProperties":false&#125; |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

---

# HTTP catalog and provider calls

Source: https://ctx4.me/docs/api-endpoints

Generated from the public Context4 OpenAPI. Authenticate with `Authorization: Bearer` and an API key. General rules: [API](https://ctx4.me/docs/api.md). Full contract: [OpenAPI JSON](https://ctx4.me/docs/openapi.json). In the JSON below, `$ref` points to a named schema in the Schemas section.

## listConnectorEndpoints

`GET /v1/connectors/{connectorId}/endpoints`

Deployment URL: `https://ctx4.me/v1/connectors/{connectorId}/endpoints`. Replace parameters in braces with actual IDs from the API.

List a connector's raw API endpoints

Capability: `tools:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectorId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `q` | query | no | &#123;"type":"string","minLength":1,"maxLength":120&#125;  |
| `group` | query | no | &#123;"type":"string","minLength":1,"maxLength":64&#125;  |
| `include_removed` | query | no | &#123;"type":"string","enum":["true","false"],"description":"`true` lists the endpoints a lock regeneration removed (with `removed_at`) beside the live ones"&#125; `true` lists the endpoints a lock regeneration removed (with `removed_at`) beside the live ones |
| `cursor` | query | no | &#123;"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"&#125; Opaque pagination cursor from a previous response |
| `limit` | query | no | &#123;"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"&#125; Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Endpoints ordered by id, without schemas, each with its descriptor; `q` matches id, path or summary, `group` narrows to one vendor group, `include_removed=true` lists tombstoned endpoints too | `application/json` [EndpointListResponse](https://ctx4.me/docs/api-schemas-4.md#endpointlistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getConnectorEndpoint

`GET /v1/connectors/{connectorId}/endpoint`

Deployment URL: `https://ctx4.me/v1/connectors/{connectorId}/endpoint`. Replace parameters in braces with actual IDs from the API.

Get one raw endpoint, by method and vendor path, with its JSON schemas

Capability: `tools:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectorId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `method` | query | yes | &#123;"type":"string","enum":["GET","POST","PUT","PATCH","DELETE","HEAD"]&#125;  |
| `path` | query | yes | &#123;"type":"string","minLength":1,"maxLength":500,"pattern":"^\\/","example":"/api/v4/leads/&#123;id&#125;"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Endpoint detail with input and output schemas and its paging descriptor | `application/json` [EndpointDetail](https://ctx4.me/docs/api-schemas-4.md#endpointdetail) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found). No such endpoint — or a lock regeneration removed it, in which case the problem detail names when, and its last descriptor digest when one was recorded (`include_removed=true` on the list still shows it) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getConnectorOpenApi

`GET /v1/connectors/{connectorId}/openapi.json`

Deployment URL: `https://ctx4.me/v1/connectors/{connectorId}/openapi.json`. Replace parameters in braces with actual IDs from the API.

The connector's mirror call surface as one OpenAPI 3.1 document

Capability: `tools:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectorId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | OpenAPI 3.1: every live catalogued endpoint as an operation on `/v1/api/&#123;connectorId&#125;` + the vendor path, with the bearer security scheme and the `Context4-Connection-Id` header on each; deterministic for an unchanged catalogue, and `ETag` carries the document's sha256 | `application/json` [ConnectorOpenApiDocument](https://ctx4.me/docs/api-schemas-4.md#connectoropenapidocument) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found). No connector of that id has catalogued endpoints | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## searchEndpoints

`POST /v1/endpoints/search`

Deployment URL: `https://ctx4.me/v1/endpoints/search`. Replace parameters in braces with actual IDs from the API.

Search raw endpoints across the connectors the caller has a usable connection for

Capability: `connections:read`.

The contract defines no additional parameters.

### Request body

Required. [EndpointSearchRequest](https://ctx4.me/docs/api-schemas-4.md#endpointsearchrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/EndpointSearchRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Hits ranked by relevance within the scope — the connectors of the workspace's active connections (or of the connections the named `borrowers` lend), narrowed by `connectors`; an empty scope answers no items and no error. `scope.index` names the index that answered (`ratel`, or `ilike` while the registry is unbuilt or disabled) | `application/json` [EndpointSearchResponse](https://ctx4.me/docs/api-schemas-4.md#endpointsearchresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## callConnectorApiGet

`GET /v1/api/{connectorId}/{vendorPath}`

Deployment URL: `https://ctx4.me/v1/api/{connectorId}/{vendorPath}`. Replace parameters in braces with actual IDs from the API.

GET a catalogued vendor endpoint through a connection (mirror path)

Capability: `executions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectorId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `vendorPath` | path | yes | &#123;"type":"string","minLength":1,"maxLength":2000,"description":"The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter","example":"api/v4/leads/7"&#125; The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter |
| `Context4-Connection-Id` | header | yes | &#123;"type":"string","format":"uuid","description":"The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)","example":"3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90"&#125; The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform` | The contract does not define a body |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## callConnectorApiPost

`POST /v1/api/{connectorId}/{vendorPath}`

Deployment URL: `https://ctx4.me/v1/api/{connectorId}/{vendorPath}`. Replace parameters in braces with actual IDs from the API.

POST a catalogued vendor endpoint through a connection (mirror path)

Capability: `executions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectorId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `vendorPath` | path | yes | &#123;"type":"string","minLength":1,"maxLength":2000,"description":"The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter","example":"api/v4/leads/7"&#125; The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter |
| `Context4-Connection-Id` | header | yes | &#123;"type":"string","format":"uuid","description":"The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)","example":"3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90"&#125; The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`) |

### Request body

Optional. [ConnectorApiBody](https://ctx4.me/docs/api-schemas-5.md#connectorapibody)

```json
{
  "required": false,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ConnectorApiBody"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform` | The contract does not define a body |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## callConnectorApiPut

`PUT /v1/api/{connectorId}/{vendorPath}`

Deployment URL: `https://ctx4.me/v1/api/{connectorId}/{vendorPath}`. Replace parameters in braces with actual IDs from the API.

PUT a catalogued vendor endpoint through a connection (mirror path)

Capability: `executions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectorId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `vendorPath` | path | yes | &#123;"type":"string","minLength":1,"maxLength":2000,"description":"The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter","example":"api/v4/leads/7"&#125; The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter |
| `Context4-Connection-Id` | header | yes | &#123;"type":"string","format":"uuid","description":"The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)","example":"3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90"&#125; The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`) |

### Request body

Optional. [ConnectorApiBody](https://ctx4.me/docs/api-schemas-5.md#connectorapibody)

```json
{
  "required": false,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ConnectorApiBody"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform` | The contract does not define a body |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## callConnectorApiPatch

`PATCH /v1/api/{connectorId}/{vendorPath}`

Deployment URL: `https://ctx4.me/v1/api/{connectorId}/{vendorPath}`. Replace parameters in braces with actual IDs from the API.

PATCH a catalogued vendor endpoint through a connection (mirror path)

Capability: `executions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectorId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `vendorPath` | path | yes | &#123;"type":"string","minLength":1,"maxLength":2000,"description":"The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter","example":"api/v4/leads/7"&#125; The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter |
| `Context4-Connection-Id` | header | yes | &#123;"type":"string","format":"uuid","description":"The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)","example":"3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90"&#125; The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`) |

### Request body

Optional. [ConnectorApiBody](https://ctx4.me/docs/api-schemas-5.md#connectorapibody)

```json
{
  "required": false,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ConnectorApiBody"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform` | The contract does not define a body |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## callConnectorApiDelete

`DELETE /v1/api/{connectorId}/{vendorPath}`

Deployment URL: `https://ctx4.me/v1/api/{connectorId}/{vendorPath}`. Replace parameters in braces with actual IDs from the API.

DELETE a catalogued vendor endpoint through a connection (mirror path)

Capability: `executions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `connectorId` | path | yes | &#123;"type":"string","pattern":"^[a-z0-9][a-z0-9-]&#123;1,78&#125;$","example":"bitrix24"&#125;  |
| `vendorPath` | path | yes | &#123;"type":"string","minLength":1,"maxLength":2000,"description":"The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter","example":"api/v4/leads/7"&#125; The vendor path after `/v1/api/&#123;connectorId&#125;/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter |
| `Context4-Connection-Id` | header | yes | &#123;"type":"string","format":"uuid","description":"The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)","example":"3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90"&#125; The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`) |

### Request body

Optional. [ConnectorApiBody](https://ctx4.me/docs/api-schemas-5.md#connectorapibody)

```json
{
  "required": false,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ConnectorApiBody"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform` | The contract does not define a body |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

---

# Composio HTTP method inventory

Source: https://ctx4.me/docs/compat-api-reference

Generated from client compat controller declarations. Replace `:` parameters with the corresponding ID. Authenticate with a Context4 API key. SDK shapes, compatibility limits and error handling: [Composio SDK](https://ctx4.me/docs/composio-sdk.md). This is an SDK adapter: its JSON envelopes differ from native `/v1` and are not described by the native OpenAPI.

This deployment's base URL: `https://ctx4.me/compat/context4/v1`.

`GET /compat/context4/v1/api/v3.1/auth_configs` currently requires both `tools:read` (the compat route) and `connections:read` (the nested auth-config read). A key with only one receives `403`. The table shows the complete required set; the route declaration separately specifies `tools:read`.

| Method | Full path | Deployment URL | Capability | Usual HTTP success |
| --- | --- | --- | --- | --- |
| GET | `/compat/context4/v1/api/v3.1/auth_configs` | `https://ctx4.me/compat/context4/v1/api/v3.1/auth_configs` | `tools:read + connections:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/auth_configs` | `https://ctx4.me/compat/context4/v1/api/v3.1/auth_configs` | `connections:write` | 200 |
| GET | `/compat/context4/v1/api/v3.1/auth_configs/:authConfigId` | `https://ctx4.me/compat/context4/v1/api/v3.1/auth_configs/:authConfigId` | `connections:read` | 200 |
| PATCH | `/compat/context4/v1/api/v3.1/auth_configs/:authConfigId` | `https://ctx4.me/compat/context4/v1/api/v3.1/auth_configs/:authConfigId` | `connections:write` | 200 |
| PATCH | `/compat/context4/v1/api/v3.1/auth_configs/:authConfigId/:status` | `https://ctx4.me/compat/context4/v1/api/v3.1/auth_configs/:authConfigId/:status` | `connections:write` | 200 |
| DELETE | `/compat/context4/v1/api/v3.1/auth_configs/:authConfigId` | `https://ctx4.me/compat/context4/v1/api/v3.1/auth_configs/:authConfigId` | `connections:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/connected_accounts` | `https://ctx4.me/compat/context4/v1/api/v3.1/connected_accounts` | `connections:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/connected_accounts/:connectionId/refresh` | `https://ctx4.me/compat/context4/v1/api/v3.1/connected_accounts/:connectionId/refresh` | `connections:write` | 200 |
| PATCH | `/compat/context4/v1/api/v3.1/connected_accounts/:connectionId` | `https://ctx4.me/compat/context4/v1/api/v3.1/connected_accounts/:connectionId` | `connections:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/connected_accounts/link` | `https://ctx4.me/compat/context4/v1/api/v3.1/connected_accounts/link` | `connections:write` | 200 |
| GET | `/compat/context4/v1/api/v3.1/connected_accounts` | `https://ctx4.me/compat/context4/v1/api/v3.1/connected_accounts` | `connections:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/connected_accounts/:connectionId` | `https://ctx4.me/compat/context4/v1/api/v3.1/connected_accounts/:connectionId` | `connections:read` | 200 |
| DELETE | `/compat/context4/v1/api/v3.1/connected_accounts/:connectionId` | `https://ctx4.me/compat/context4/v1/api/v3.1/connected_accounts/:connectionId` | `connections:write` | 200 |
| PATCH | `/compat/context4/v1/api/v3.1/connected_accounts/:connectionId/status` | `https://ctx4.me/compat/context4/v1/api/v3.1/connected_accounts/:connectionId/status` | `connections:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/endpoints/list` | `https://ctx4.me/compat/context4/v1/api/v3.1/endpoints/list` | `tools:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/endpoints/describe` | `https://ctx4.me/compat/context4/v1/api/v3.1/endpoints/describe` | `tools:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/endpoints/search` | `https://ctx4.me/compat/context4/v1/api/v3.1/endpoints/search` | `connections:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/endpoints/execute` | `https://ctx4.me/compat/context4/v1/api/v3.1/endpoints/execute` | `executions:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/endpoints/executions/lookup` | `https://ctx4.me/compat/context4/v1/api/v3.1/endpoints/executions/lookup` | `executions:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/files/upload/request` | `https://ctx4.me/compat/context4/v1/api/v3.1/files/upload/request` | `executions:write` | 200 |
| GET | `/compat/context4/v1/api/v3.1/files/list` | `https://ctx4.me/compat/context4/v1/api/v3.1/files/list` | `executions:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/mcp/servers` | `https://ctx4.me/compat/context4/v1/api/v3.1/mcp/servers` | `tool-sessions:write` | 200 |
| GET | `/compat/context4/v1/api/v3.1/mcp/servers` | `https://ctx4.me/compat/context4/v1/api/v3.1/mcp/servers` | `tool-sessions:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/mcp/app/:appKey` | `https://ctx4.me/compat/context4/v1/api/v3.1/mcp/app/:appKey` | `tool-sessions:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/mcp/:id` | `https://ctx4.me/compat/context4/v1/api/v3.1/mcp/:id` | `tool-sessions:read` | 200 |
| PATCH | `/compat/context4/v1/api/v3.1/mcp/:id` | `https://ctx4.me/compat/context4/v1/api/v3.1/mcp/:id` | `tool-sessions:write` | 200 |
| DELETE | `/compat/context4/v1/api/v3.1/mcp/:id` | `https://ctx4.me/compat/context4/v1/api/v3.1/mcp/:id` | `tool-sessions:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/mcp/servers/generate` | `https://ctx4.me/compat/context4/v1/api/v3.1/mcp/servers/generate` | `tool-sessions:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/mcp/servers/custom` | `https://ctx4.me/compat/context4/v1/api/v3.1/mcp/servers/custom` | `tool-sessions:write` | 200 |
| GET | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/mounts/:mountID/items` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/mounts/:mountID/items` | `tool-sessions:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/mounts/:mountID/delete` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/mounts/:mountID/delete` | `tool-sessions:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/mounts/:mountID/upload_url` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/mounts/:mountID/upload_url` | `tool-sessions:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/mounts/:mountID/download_url` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/mounts/:mountID/download_url` | `tool-sessions:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/attach` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/attach` | `tool-sessions:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/toolkits` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/toolkits` | `tool-sessions:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/config_history` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/config_history` | `tool-sessions:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/search` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/search` | `tool-sessions:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/proxy_execute` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/proxy_execute` | `executions:write` | 200 |
| GET | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/tools` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/tools` | `tool-sessions:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/execute_meta` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/execute_meta` | `executions:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/execute` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/execute` | `executions:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tools/execute/proxy` | `https://ctx4.me/compat/context4/v1/api/v3.1/tools/execute/proxy` | `executions:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tools/execute/:toolSlug` | `https://ctx4.me/compat/context4/v1/api/v3.1/tools/execute/:toolSlug` | `executions:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/internal/action_execution/logs` | `https://ctx4.me/compat/context4/v1/api/v3.1/internal/action_execution/logs` | `executions:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/internal/action_execution/log/:logId` | `https://ctx4.me/compat/context4/v1/api/v3.1/internal/action_execution/log/:logId` | `executions:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session` | `tool-sessions:write` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/link` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId/link` | `connections:write` | 200 |
| GET | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId` | `tool-sessions:read` | 200 |
| PATCH | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId` | `tool-sessions:write` | 200 |
| DELETE | `/compat/context4/v1/api/v3.1/tool_router/session/:sessionId` | `https://ctx4.me/compat/context4/v1/api/v3.1/tool_router/session/:sessionId` | `tool-sessions:write` | 200 |
| GET | `/compat/context4/v1/api/v3.1/toolkits` | `https://ctx4.me/compat/context4/v1/api/v3.1/toolkits` | `tools:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/toolkits/categories` | `https://ctx4.me/compat/context4/v1/api/v3.1/toolkits/categories` | `tools:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/toolkits/:toolkitSlug` | `https://ctx4.me/compat/context4/v1/api/v3.1/toolkits/:toolkitSlug` | `tools:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/tools` | `https://ctx4.me/compat/context4/v1/api/v3.1/tools` | `tools:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/tools/enum` | `https://ctx4.me/compat/context4/v1/api/v3.1/tools/enum` | `tools:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/tools/execute/:toolSlug/input` | `https://ctx4.me/compat/context4/v1/api/v3.1/tools/execute/:toolSlug/input` | `tools:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/tools/:toolSlug` | `https://ctx4.me/compat/context4/v1/api/v3.1/tools/:toolSlug` | `tools:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/triggers_types` | `https://ctx4.me/compat/context4/v1/api/v3.1/triggers_types` | `tools:read` | 200 |
| GET | `/compat/context4/v1/api/v3.1/triggers_types/:triggerSlug` | `https://ctx4.me/compat/context4/v1/api/v3.1/triggers_types/:triggerSlug` | `tools:read` | 200 |
| POST | `/compat/context4/v1/api/v3.1/trigger_instances/:triggerSlug/upsert` | `https://ctx4.me/compat/context4/v1/api/v3.1/trigger_instances/:triggerSlug/upsert` | `executions:write` | 501 |
| DELETE | `/compat/context4/v1/api/v3.1/trigger_instances/manage/:triggerId` | `https://ctx4.me/compat/context4/v1/api/v3.1/trigger_instances/manage/:triggerId` | `executions:write` | 501 |

A usual HTTP success does not mean the action succeeded: check the SDK envelope, `successful` and `error`. Trigger stubs and unavailable capabilities can reject requests. The first-party platform's external endpoint automation catalog is not a client SDK API and is excluded from this inventory.

---

# API schemas: part 1

Source: https://ctx4.me/docs/api-schemas-1

Exact field names, required, enum, nullable and constraints are preserved from [OpenAPI](https://ctx4.me/docs/openapi.json). `$ref` resolves relative to `components.schemas` in the full document. All parts: [1](https://ctx4.me/docs/api-schemas-1.md), [2](https://ctx4.me/docs/api-schemas-2.md), [3](https://ctx4.me/docs/api-schemas-3.md), [4](https://ctx4.me/docs/api-schemas-4.md).

## Problem


```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "status": {
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "code": {
      "type": "string",
      "enum": [
        "validation_failed",
        "authentication_required",
        "invalid_api_key",
        "api_key_expired",
        "api_key_revoked",
        "invalid_oauth_token",
        "oauth_token_expired",
        "oauth_grant_revoked",
        "workspace_selection_required",
        "capability_missing",
        "forbidden",
        "not_found",
        "conflict",
        "idempotency_conflict",
        "execution_not_cancellable",
        "session_expired",
        "session_revoked",
        "session_call_budget_exhausted",
        "rate_limited",
        "quota_exceeded",
        "connector_version_unavailable",
        "provider_unavailable",
        "service_unavailable",
        "internal"
      ]
    },
    "request_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "detail": {
      "type": "string",
      "maxLength": 256
    }
  },
  "required": [
    "type",
    "title",
    "status",
    "code",
    "request_id"
  ],
  "additionalProperties": false,
  "description": "RFC7807-style problem document. `code` is the stable machine-readable registry entry."
}
```

## ToolListResponse

Related schemas: [ToolSummary](https://ctx4.me/docs/api-schemas-1.md#toolsummary).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ToolSummary"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## ToolSummary


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}\\.[a-z0-9][a-z0-9_.]{1,78}$",
      "example": "bitrix24.contact.create"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "connector_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_.]{1,78}$",
      "example": "contact.create"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2000
    }
  },
  "required": [
    "id",
    "connector_id",
    "connector_version",
    "operation_id",
    "name",
    "description"
  ],
  "additionalProperties": false
}
```

## ToolDetail


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}\\.[a-z0-9][a-z0-9_.]{1,78}$",
      "example": "bitrix24.contact.create"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "connector_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_.]{1,78}$",
      "example": "contact.create"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2000
    },
    "input_schema": {},
    "output_schema": {}
  },
  "required": [
    "id",
    "connector_id",
    "connector_version",
    "operation_id",
    "name",
    "description"
  ],
  "additionalProperties": false,
  "description": "Tool with its pinned JSON-schema documents (published catalog version)"
}
```

## PublicIdentity


```json
{
  "type": "object",
  "properties": {
    "organization_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "organization_id",
    "workspace_id"
  ],
  "additionalProperties": false
}
```

## Execution

Related schemas: [ExecutionEndUserRef](https://ctx4.me/docs/api-schemas-1.md#executionenduserref).

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "status": {
      "type": "string",
      "enum": [
        "requested",
        "queued",
        "running",
        "retrying",
        "succeeded",
        "failed",
        "rejected",
        "cancelled"
      ]
    },
    "source": {
      "type": "string",
      "enum": [
        "dashboard",
        "api",
        "mcp",
        "compat"
      ]
    },
    "user_id": {
      "$ref": "#/components/schemas/ExecutionEndUserRef"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "connector_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "operation_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "tool_session_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "project_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "denial_code": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "policy_denied",
        "quota_exhausted",
        "connector_version_unavailable",
        "connection_unavailable",
        "session_denied",
        null
      ]
    },
    "failure_code": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "provider_timeout",
        "provider_rate_limited",
        "provider_unavailable",
        "connection_revoked",
        "invalid_input",
        "provider_rejected",
        "attempt_lost",
        "engine_error",
        "retries_exhausted",
        null
      ]
    },
    "attempt_count": {
      "type": "integer",
      "minimum": 0
    },
    "max_attempts": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "next_retry_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "queued_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "finished_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "status",
    "source",
    "user_id",
    "connector_id",
    "connector_version",
    "operation_id",
    "connection_id",
    "tool_session_id",
    "project_id",
    "denial_code",
    "failure_code",
    "attempt_count",
    "max_attempts",
    "next_retry_at",
    "version",
    "created_at",
    "updated_at",
    "queued_at",
    "finished_at"
  ],
  "additionalProperties": false
}
```

## ExecutionEndUserRef


```json
{
  "type": "string",
  "pattern": "^[A-Za-z0-9][A-Za-z0-9 _.:@-]{0,255}$"
}
```

## CreateExecutionRequest


```json
{
  "type": "object",
  "properties": {
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_.]{1,78}$",
      "example": "contact.create"
    },
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "tool_session_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "tool_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}\\.[a-z0-9][a-z0-9_.]{1,78}$",
      "example": "bitrix24.contact.create"
    },
    "project_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "input": {
      "description": "Bounded JSON payload (<= 64 KiB serialized)"
    }
  },
  "additionalProperties": false
}
```

## ExecutionListResponse

Related schemas: [Execution](https://ctx4.me/docs/api-schemas-1.md#execution).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Execution"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## ExecutionWithResult

Related schemas: [ExecutionEndUserRef](https://ctx4.me/docs/api-schemas-1.md#executionenduserref), [ExecutionResult](https://ctx4.me/docs/api-schemas-1.md#executionresult).

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "status": {
      "type": "string",
      "enum": [
        "requested",
        "queued",
        "running",
        "retrying",
        "succeeded",
        "failed",
        "rejected",
        "cancelled"
      ]
    },
    "source": {
      "type": "string",
      "enum": [
        "dashboard",
        "api",
        "mcp",
        "compat"
      ]
    },
    "user_id": {
      "$ref": "#/components/schemas/ExecutionEndUserRef"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "connector_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "operation_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "tool_session_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "project_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "denial_code": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "policy_denied",
        "quota_exhausted",
        "connector_version_unavailable",
        "connection_unavailable",
        "session_denied",
        null
      ]
    },
    "failure_code": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "provider_timeout",
        "provider_rate_limited",
        "provider_unavailable",
        "connection_revoked",
        "invalid_input",
        "provider_rejected",
        "attempt_lost",
        "engine_error",
        "retries_exhausted",
        null
      ]
    },
    "attempt_count": {
      "type": "integer",
      "minimum": 0
    },
    "max_attempts": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "next_retry_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "queued_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "finished_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "result": {
      "$ref": "#/components/schemas/ExecutionResult"
    }
  },
  "required": [
    "id",
    "status",
    "source",
    "user_id",
    "connector_id",
    "connector_version",
    "operation_id",
    "connection_id",
    "tool_session_id",
    "project_id",
    "denial_code",
    "failure_code",
    "attempt_count",
    "max_attempts",
    "next_retry_at",
    "version",
    "created_at",
    "updated_at",
    "queued_at",
    "finished_at",
    "result"
  ],
  "additionalProperties": false
}
```

## ExecutionResult


```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "inline"
          ]
        },
        "data": {}
      },
      "required": [
        "kind"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "url"
          ]
        },
        "url": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-07-16T12:00:00.000Z"
        }
      },
      "required": [
        "kind",
        "url",
        "expires_at"
      ],
      "additionalProperties": false
    },
    {
      "type": "null"
    }
  ],
  "description": "Inline normalized result or a short-lived signed download URL"
}
```

## AttemptListResponse

Related schemas: [ExecutionAttempt](https://ctx4.me/docs/api-schemas-1.md#executionattempt).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ExecutionAttempt"
      }
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false
}
```

## ExecutionAttempt


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "execution_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "attempt_number": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "outcome": {
      "type": "string",
      "enum": [
        "succeeded",
        "failed_transient",
        "failed_permanent",
        "lost"
      ]
    },
    "error_code": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "provider_timeout",
        "provider_rate_limited",
        "provider_unavailable",
        "connection_revoked",
        "invalid_input",
        "provider_rejected",
        "attempt_lost",
        "engine_error",
        "retries_exhausted",
        null
      ]
    },
    "error_message": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 500
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "finished_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "latency_ms": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "id",
    "execution_id",
    "attempt_number",
    "outcome",
    "error_code",
    "error_message",
    "started_at",
    "finished_at",
    "latency_ms"
  ],
  "additionalProperties": false,
  "description": "Append-only attempt record; engine identifiers are deliberately not exposed"
}
```

## CancelExecutionRequest


```json
{
  "type": "object",
  "properties": {
    "expected_version": {
      "type": "integer",
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "expected_version"
  ],
  "additionalProperties": false
}
```

## ConnectionListResponse

Related schemas: [Connection](https://ctx4.me/docs/api-schemas-1.md#connection).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Connection"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## Connection

Related schemas: [EndUserRef](https://ctx4.me/docs/api-schemas-2.md#enduserref).

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "connector_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "auth_method": {
      "type": "string",
      "enum": [
        "oauth2",
        "api_key"
      ]
    },
    "user_id": {
      "$ref": "#/components/schemas/EndUserRef"
    },
    "is_default": {
      "type": "boolean"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "active",
        "degraded",
        "revoked",
        "failed"
      ]
    },
    "status_reason": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 120
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "activated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "connector_id",
    "connector_version",
    "name",
    "auth_method",
    "user_id",
    "is_default",
    "status",
    "status_reason",
    "version",
    "created_at",
    "activated_at"
  ],
  "additionalProperties": false
}
```

---

# API schemas: part 2

Source: https://ctx4.me/docs/api-schemas-2

Exact field names, required, enum, nullable and constraints are preserved from [OpenAPI](https://ctx4.me/docs/openapi.json). `$ref` resolves relative to `components.schemas` in the full document. All parts: [1](https://ctx4.me/docs/api-schemas-1.md), [2](https://ctx4.me/docs/api-schemas-2.md), [3](https://ctx4.me/docs/api-schemas-3.md), [4](https://ctx4.me/docs/api-schemas-4.md).

## EndUserRef


```json
{
  "type": "string",
  "pattern": "^[A-Za-z0-9][A-Za-z0-9 _.:@-]{0,255}$"
}
```

## HostedAuthLink


```json
{
  "type": "object",
  "properties": {
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "connect_url": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "connection_id",
    "connect_url",
    "expires_at"
  ],
  "additionalProperties": false,
  "description": "Hosted authorization link; direct the end user to connect_url before it expires"
}
```

## CreateConnectionRequest

Related schemas: [EndUserRef](https://ctx4.me/docs/api-schemas-2.md#enduserref).

```json
{
  "type": "object",
  "properties": {
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "user_id": {
      "$ref": "#/components/schemas/EndUserRef"
    },
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120,
      "pattern": "^[\\p{L}\\p{N}][\\p{L}\\p{N}\\p{Pd} _.]+$"
    },
    "resume": {
      "type": "object",
      "properties": {
        "connection_id": {
          "type": "string",
          "format": "uuid",
          "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
        },
        "expected_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        }
      },
      "required": [
        "connection_id",
        "expected_version"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "connector_id",
    "name"
  ],
  "additionalProperties": false,
  "description": "Initiates hosted OAuth authorization. Optional resume renews an unactivated connection in place; account identity must match and expected_version guards concurrent attempts."
}
```

## AuthConfigListResponse

Related schemas: [AuthConfig](https://ctx4.me/docs/api-schemas-2.md#authconfig).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AuthConfig"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## AuthConfig


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "mode": {
      "type": "string",
      "enum": [
        "managed",
        "custom"
      ]
    },
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "client_id_mask": {
      "type": "string",
      "maxLength": 24
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256
      },
      "maxItems": 64
    },
    "status": {
      "type": "string",
      "enum": [
        "enabled",
        "disabled"
      ]
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "connector_id",
    "mode",
    "name",
    "client_id_mask",
    "scopes",
    "status",
    "version",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

## CreateAuthConfigRequest


```json
{
  "type": "object",
  "properties": {
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "mode": {
      "type": "string",
      "enum": [
        "managed",
        "custom"
      ]
    },
    "client_id": {
      "type": "string",
      "minLength": 4,
      "maxLength": 512
    },
    "client_secret": {
      "type": "string",
      "minLength": 8,
      "maxLength": 4096
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256
      },
      "maxItems": 64
    }
  },
  "required": [
    "connector_id",
    "name"
  ],
  "additionalProperties": false,
  "description": "Registers a named auth configuration; a custom mode requires the tenant's OAuth client, whose secret is delivered once to the engine boundary and never echoed"
}
```

## UpdateAuthConfigRequest


```json
{
  "type": "object",
  "properties": {
    "expected_version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "status": {
      "type": "string",
      "enum": [
        "enabled",
        "disabled"
      ]
    }
  },
  "required": [
    "expected_version"
  ],
  "additionalProperties": false
}
```

## NetworkAttachment


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "mode": {
      "type": "string",
      "enum": [
        "direct",
        "wireguard",
        "openvpn"
      ]
    },
    "destinations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string",
            "minLength": 1,
            "maxLength": 253,
            "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"
          },
          "port": {
            "type": "integer",
            "minimum": 1,
            "maximum": 65535
          }
        },
        "required": [
          "host",
          "port"
        ],
        "additionalProperties": false
      }
    },
    "dns_servers": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "format": "ip"
          },
          {
            "type": "string",
            "format": "ip"
          }
        ]
      },
      "maxItems": 3
    },
    "connection_enabled": {
      "type": "boolean"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "provisioning",
        "active",
        "degraded",
        "draining",
        "ready_to_revoke",
        "revoked",
        "failed"
      ]
    },
    "status_reason": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 120
    },
    "desired_generation": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "observed_generation": {
      "type": "integer",
      "minimum": 0
    },
    "active_lease_count": {
      "type": "integer",
      "minimum": 0
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "last_health_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "revoked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "name",
    "mode",
    "destinations",
    "dns_servers",
    "connection_enabled",
    "status",
    "status_reason",
    "desired_generation",
    "observed_generation",
    "active_lease_count",
    "version",
    "last_health_at",
    "revoked_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

## NetworkAttachmentList

Related schemas: [NetworkAttachment](https://ctx4.me/docs/api-schemas-2.md#networkattachment).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/NetworkAttachment"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## CreateNetworkAttachmentRequest


```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "dns_servers": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string",
                "format": "ip"
              },
              {
                "type": "string",
                "format": "ip"
              }
            ]
          },
          "maxItems": 3
        },
        "name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 120
        },
        "destinations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "host": {
                "type": "string",
                "minLength": 1,
                "maxLength": 253,
                "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"
              },
              "port": {
                "type": "integer",
                "minimum": 1,
                "maximum": 65535
              }
            },
            "required": [
              "host",
              "port"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "maxItems": 64
        },
        "mode": {
          "type": "string",
          "enum": [
            "direct"
          ]
        }
      },
      "required": [
        "name",
        "destinations",
        "mode"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "dns_servers": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string",
                "format": "ip"
              },
              {
                "type": "string",
                "format": "ip"
              }
            ]
          },
          "maxItems": 3
        },
        "name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 120
        },
        "destinations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "host": {
                "type": "string",
                "minLength": 1,
                "maxLength": 253,
                "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"
              },
              "port": {
                "type": "integer",
                "minimum": 1,
                "maximum": 65535
              }
            },
            "required": [
              "host",
              "port"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "maxItems": 64
        },
        "mode": {
          "type": "string",
          "enum": [
            "wireguard"
          ]
        },
        "credential": {
          "type": "object",
          "properties": {
            "private_key": {
              "type": "string",
              "minLength": 32,
              "maxLength": 256
            },
            "peer_public_key": {
              "type": "string",
              "minLength": 32,
              "maxLength": 256
            },
            "preshared_key": {
              "type": "string",
              "minLength": 32,
              "maxLength": 256
            },
            "endpoint_host": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253,
              "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"
            },
            "endpoint_port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            },
            "interface_addresses": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 3,
                "maxLength": 64
              },
              "minItems": 1,
              "maxItems": 8
            }
          },
          "required": [
            "private_key",
            "peer_public_key",
            "endpoint_host",
            "endpoint_port",
            "interface_addresses"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "name",
        "destinations",
        "mode",
        "credential"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "dns_servers": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string",
                "format": "ip"
              },
              {
                "type": "string",
                "format": "ip"
              }
            ]
          },
          "maxItems": 3
        },
        "name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 120
        },
        "destinations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "host": {
                "type": "string",
                "minLength": 1,
                "maxLength": 253,
                "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"
              },
              "port": {
                "type": "integer",
                "minimum": 1,
                "maximum": 65535
              }
            },
            "required": [
              "host",
              "port"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "maxItems": 64
        },
        "mode": {
          "type": "string",
          "enum": [
            "openvpn"
          ]
        },
        "credential": {
          "type": "object",
          "properties": {
            "options": {
              "type": "object",
              "properties": {
                "cipher": {
                  "type": "string",
                  "enum": [
                    "AES-256-GCM",
                    "AES-128-GCM",
                    "CHACHA20-POLY1305"
                  ]
                },
                "auth": {
                  "type": "string",
                  "enum": [
                    "none",
                    "SHA1",
                    "SHA256",
                    "SHA512"
                  ]
                },
                "tun_mtu": {
                  "type": "integer",
                  "minimum": 576,
                  "maximum": 9000
                },
                "ping": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 3600
                },
                "ping_restart": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 86400
                },
                "connect_retry": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 300
                },
                "reneg_sec": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 604800
                },
                "persist_tun": {
                  "type": "boolean"
                },
                "persist_key": {
                  "type": "boolean"
                },
                "mute_replay_warnings": {
                  "type": "boolean"
                },
                "verb": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 4
                }
              },
              "additionalProperties": false
            },
            "remote_host": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253,
              "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"
            },
            "remote_port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            },
            "protocol": {
              "type": "string",
              "enum": [
                "udp",
                "tcp"
              ]
            },
            "ca_certificate": {
              "type": "string",
              "minLength": 64,
              "maxLength": 16384
            },
            "client_certificate": {
              "type": "string",
              "minLength": 64,
              "maxLength": 16384
            },
            "client_key": {
              "type": "string",
              "minLength": 64,
              "maxLength": 16384
            },
            "tls_auth_key": {
              "type": "string",
              "minLength": 64,
              "maxLength": 16384
            },
            "tls_auth_direction": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            },
            "username": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256,
              "pattern": "^[^\\0\\r\\n]+$"
            },
            "password": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4096,
              "pattern": "^[^\\0\\r\\n]+$"
            }
          },
          "required": [
            "remote_host",
            "remote_port",
            "protocol",
            "ca_certificate",
            "client_certificate",
            "client_key"
          ],
          "additionalProperties": false,
          "not": {
            "required": [
              "options",
              "tls_auth_key"
            ],
            "properties": {
              "options": {
                "required": [
                  "auth"
                ],
                "properties": {
                  "auth": {
                    "enum": [
                      "none"
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "required": [
        "name",
        "destinations",
        "mode",
        "credential"
      ],
      "additionalProperties": false
    }
  ],
  "description": "Typed private-network configuration; arbitrary OpenVPN/WireGuard files, scripts, plugins, and routes are not accepted"
}
```

## DiscoverPostgresDatabasesResponse


```json
{
  "type": "object",
  "properties": {
    "databases": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "access": {
            "type": "string",
            "enum": [
              "verified",
              "candidate",
              "denied"
            ]
          },
          "connect_privilege": {
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "access",
          "connect_privilege"
        ],
        "additionalProperties": false
      },
      "maxItems": 100
    },
    "incomplete": {
      "type": "boolean"
    },
    "seed_database": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "error_code": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "network_unavailable",
        "authentication_failed",
        "login_trigger_failed",
        "tls_failed",
        "tls_configuration_unsupported",
        "seed_database_unavailable",
        "catalog_denied",
        "discovery_unavailable",
        null
      ]
    }
  },
  "required": [
    "databases",
    "incomplete",
    "seed_database",
    "error_code"
  ],
  "additionalProperties": false
}
```

## DataSourceConnection

Related schemas: [DataSourceAttentionReason](https://ctx4.me/docs/api-schemas-2.md#datasourceattentionreason).

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "kind": {
      "type": "string",
      "enum": [
        "postgres",
        "mysql",
        "sqlserver",
        "mongodb",
        "topic"
      ]
    },
    "endpoint": {
      "type": "object",
      "properties": {
        "hosts": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 253
          },
          "minItems": 1,
          "maxItems": 20
        },
        "port": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 65535
        },
        "resource": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "authentication": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        },
        "tls_mode": {
          "type": "string",
          "enum": [
            "require",
            "verify_ca",
            "verify_full",
            "mutual_tls"
          ]
        },
        "custom_ca": {
          "type": "boolean"
        },
        "mutual_tls": {
          "type": "boolean"
        }
      },
      "required": [
        "hosts",
        "port",
        "resource",
        "authentication",
        "tls_mode",
        "custom_ca",
        "mutual_tls"
      ],
      "additionalProperties": false
    },
    "credential_version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "network_attachment_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "active",
        "degraded",
        "revoked",
        "failed"
      ]
    },
    "status_reason": {
      "$ref": "#/components/schemas/DataSourceAttentionReason"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "name",
    "kind",
    "endpoint",
    "credential_version",
    "network_attachment_id",
    "status",
    "status_reason",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

## DataSourceAttentionReason


```json
{
  "type": [
    "string",
    "null"
  ],
  "enum": [
    "authentication_failed",
    "login_trigger_failed",
    "catalog_denied",
    "tls_failed",
    null
  ],
  "description": "Source-side condition a person must fix; set only while the connection is degraded"
}
```

## AddDatabaseFromConnectionRequest


```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "database": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "name",
    "database"
  ],
  "additionalProperties": false
}
```

## DiscoverPostgresDatabasesRequest


```json
{
  "type": "object",
  "properties": {
    "network_attachment_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "source": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "postgres",
            "sqlserver"
          ]
        },
        "host": {
          "type": "string",
          "minLength": 1,
          "maxLength": 253
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535
        },
        "seed_database": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "authentication": {
          "type": "string",
          "enum": [
            "username_password"
          ]
        },
        "credential": {
          "type": "object",
          "properties": {
            "username": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256
            },
            "password": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4096
            }
          },
          "required": [
            "username",
            "password"
          ],
          "additionalProperties": false
        },
        "tls": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "mode": {
                  "type": "string",
                  "enum": [
                    "require"
                  ]
                }
              },
              "required": [
                "mode"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "mode": {
                  "type": "string",
                  "enum": [
                    "verify_ca",
                    "verify_full"
                  ]
                },
                "ca_certificate": {
                  "type": "string",
                  "minLength": 64,
                  "maxLength": 32768
                }
              },
              "required": [
                "mode",
                "ca_certificate"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "mode": {
                  "type": "string",
                  "enum": [
                    "mutual_tls"
                  ]
                },
                "ca_certificate": {
                  "type": "string",
                  "minLength": 64,
                  "maxLength": 32768
                },
                "client_certificate": {
                  "type": "string",
                  "minLength": 64,
                  "maxLength": 32768
                },
                "client_key": {
                  "type": "string",
                  "minLength": 64,
                  "maxLength": 32768
                }
              },
              "required": [
                "mode",
                "ca_certificate",
                "client_certificate",
                "client_key"
              ],
              "additionalProperties": false
            }
          ]
        }
      },
      "required": [
        "kind",
        "host",
        "port",
        "authentication",
        "credential",
        "tls"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "source"
  ],
  "additionalProperties": false
}
```

## DataSourceConnectionList

Related schemas: [DataSourceConnection](https://ctx4.me/docs/api-schemas-2.md#datasourceconnection).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/DataSourceConnection"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

---

# API schemas: part 3

Source: https://ctx4.me/docs/api-schemas-3

Exact field names, required, enum, nullable and constraints are preserved from [OpenAPI](https://ctx4.me/docs/openapi.json). `$ref` resolves relative to `components.schemas` in the full document. All parts: [1](https://ctx4.me/docs/api-schemas-1.md), [2](https://ctx4.me/docs/api-schemas-2.md), [3](https://ctx4.me/docs/api-schemas-3.md), [4](https://ctx4.me/docs/api-schemas-4.md).

## CreateDataSourceConnectionRequest


```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "network_attachment_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "source": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "host": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253
            },
            "port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            },
            "database": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "tls": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "require"
                      ]
                    }
                  },
                  "required": [
                    "mode"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "verify_full"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "kind": {
              "type": "string",
              "enum": [
                "sqlserver"
              ]
            },
            "authentication": {
              "type": "string",
              "enum": [
                "username_password"
              ]
            },
            "credential": {
              "type": "object",
              "properties": {
                "username": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "password": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                }
              },
              "required": [
                "username",
                "password"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "host",
            "port",
            "database",
            "tls",
            "kind",
            "authentication",
            "credential"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "host": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253
            },
            "port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            },
            "database": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "tls": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "require"
                      ]
                    }
                  },
                  "required": [
                    "mode"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "verify_ca",
                        "verify_full"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "mutual_tls"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_key": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate",
                    "client_certificate",
                    "client_key"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "kind": {
              "type": "string",
              "enum": [
                "postgres"
              ]
            },
            "authentication": {
              "type": "string",
              "enum": [
                "username_password"
              ]
            },
            "credential": {
              "type": "object",
              "properties": {
                "username": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "password": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                }
              },
              "required": [
                "username",
                "password"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "host",
            "port",
            "database",
            "tls",
            "kind",
            "authentication",
            "credential"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "host": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253
            },
            "port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            },
            "database": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "tls": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "require"
                      ]
                    }
                  },
                  "required": [
                    "mode"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "verify_ca",
                        "verify_full"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "mutual_tls"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_key": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate",
                    "client_certificate",
                    "client_key"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "kind": {
              "type": "string",
              "enum": [
                "mysql"
              ]
            },
            "authentication": {
              "type": "string",
              "enum": [
                "username_password"
              ]
            },
            "credential": {
              "type": "object",
              "properties": {
                "username": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "password": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                }
              },
              "required": [
                "username",
                "password"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "host",
            "port",
            "database",
            "tls",
            "kind",
            "authentication",
            "credential"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "host": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253
            },
            "port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            },
            "database": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "tls": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "require"
                      ]
                    }
                  },
                  "required": [
                    "mode"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "verify_ca",
                        "verify_full"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "mutual_tls"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_key": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate",
                    "client_certificate",
                    "client_key"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "kind": {
              "type": "string",
              "enum": [
                "mongodb"
              ]
            },
            "replica_set": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "authentication": {
              "type": "string",
              "enum": [
                "username_password"
              ]
            },
            "credential": {
              "type": "object",
              "properties": {
                "username": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "password": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                }
              },
              "required": [
                "username",
                "password"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "host",
            "port",
            "database",
            "tls",
            "kind",
            "replica_set",
            "authentication",
            "credential"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "host": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253
            },
            "port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            },
            "database": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "tls": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "require"
                      ]
                    }
                  },
                  "required": [
                    "mode"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "verify_ca",
                        "verify_full"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "mutual_tls"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_key": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate",
                    "client_certificate",
                    "client_key"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "kind": {
              "type": "string",
              "enum": [
                "mongodb"
              ]
            },
            "replica_set": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "authentication": {
              "type": "string",
              "enum": [
                "x509"
              ]
            },
            "credential": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            }
          },
          "required": [
            "host",
            "port",
            "database",
            "tls",
            "kind",
            "replica_set",
            "authentication",
            "credential"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "bootstrap_servers": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "host": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "port": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535
                  }
                },
                "required": [
                  "host",
                  "port"
                ],
                "additionalProperties": false
              },
              "minItems": 1,
              "maxItems": 20
            },
            "topic": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "tls": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "require"
                      ]
                    }
                  },
                  "required": [
                    "mode"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "verify_ca",
                        "verify_full"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "mutual_tls"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_key": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate",
                    "client_certificate",
                    "client_key"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "kind": {
              "type": "string",
              "enum": [
                "topic"
              ]
            },
            "authentication": {
              "type": "string",
              "enum": [
                "sasl_scram_256"
              ]
            },
            "credential": {
              "type": "object",
              "properties": {
                "username": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "password": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                }
              },
              "required": [
                "username",
                "password"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "bootstrap_servers",
            "topic",
            "tls",
            "kind",
            "authentication",
            "credential"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "bootstrap_servers": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "host": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "port": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535
                  }
                },
                "required": [
                  "host",
                  "port"
                ],
                "additionalProperties": false
              },
              "minItems": 1,
              "maxItems": 20
            },
            "topic": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "tls": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "require"
                      ]
                    }
                  },
                  "required": [
                    "mode"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "verify_ca",
                        "verify_full"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "mutual_tls"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_key": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate",
                    "client_certificate",
                    "client_key"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "kind": {
              "type": "string",
              "enum": [
                "topic"
              ]
            },
            "authentication": {
              "type": "string",
              "enum": [
                "sasl_scram_512"
              ]
            },
            "credential": {
              "type": "object",
              "properties": {
                "username": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "password": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                }
              },
              "required": [
                "username",
                "password"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "bootstrap_servers",
            "topic",
            "tls",
            "kind",
            "authentication",
            "credential"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "bootstrap_servers": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "host": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "port": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535
                  }
                },
                "required": [
                  "host",
                  "port"
                ],
                "additionalProperties": false
              },
              "minItems": 1,
              "maxItems": 20
            },
            "topic": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "tls": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "require"
                      ]
                    }
                  },
                  "required": [
                    "mode"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "verify_ca",
                        "verify_full"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "mutual_tls"
                      ]
                    },
                    "ca_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_certificate": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    },
                    "client_key": {
                      "type": "string",
                      "minLength": 64,
                      "maxLength": 32768
                    }
                  },
                  "required": [
                    "mode",
                    "ca_certificate",
                    "client_certificate",
                    "client_key"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "kind": {
              "type": "string",
              "enum": [
                "topic"
              ]
            },
            "authentication": {
              "type": "string",
              "enum": [
                "mutual_tls"
              ]
            },
            "credential": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            }
          },
          "required": [
            "bootstrap_servers",
            "topic",
            "tls",
            "kind",
            "authentication",
            "credential"
          ],
          "additionalProperties": false
        }
      ]
    }
  },
  "required": [
    "name",
    "source"
  ],
  "additionalProperties": false,
  "description": "Typed source settings; raw DSNs, secret references, connector configs, and executable content are not accepted"
}
```

## ReplaceDataSourceCredentialRequest


```json
{
  "type": "object",
  "properties": {
    "credential": {
      "type": "object",
      "properties": {
        "username": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "password": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        }
      },
      "required": [
        "username",
        "password"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "credential"
  ],
  "additionalProperties": false,
  "description": "A new username and password for a password-authenticated source; stored as the next secret version and never returned"
}
```

## SourceSchema


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "source_connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "source_technology": {
      "type": "string",
      "enum": [
        "postgres",
        "mysql",
        "mongodb",
        "sqlserver",
        "topic"
      ]
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "hash": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "entities": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "key_fields": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "maxItems": 64
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "type": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "nullable": {
                  "type": "boolean"
                }
              },
              "required": [
                "name",
                "type",
                "nullable"
              ],
              "additionalProperties": false
            },
            "minItems": 1,
            "maxItems": 2000
          }
        },
        "required": [
          "name",
          "key_fields",
          "fields"
        ],
        "additionalProperties": false
      },
      "maxItems": 500
    },
    "capabilities": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 120
      },
      "maxItems": 64
    },
    "incomplete": {
      "type": "boolean"
    },
    "compatibility": {
      "type": "string",
      "enum": [
        "initial",
        "compatible",
        "breaking"
      ]
    },
    "breaking_reasons": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 500
      },
      "maxItems": 2000
    },
    "predecessor_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "source_connection_id",
    "source_technology",
    "version",
    "hash",
    "entities",
    "capabilities",
    "incomplete",
    "compatibility",
    "breaking_reasons",
    "predecessor_id",
    "created_at"
  ],
  "additionalProperties": false
}
```

## ProviderSchema


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "connector_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "entity": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "hash": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "key_fields": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "provider_name": {
            "type": "string",
            "minLength": 1
          },
          "definition": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "name",
          "provider_name",
          "definition"
        ],
        "additionalProperties": false
      },
      "minItems": 1
    },
    "predecessor_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "connection_id",
    "connector_id",
    "entity",
    "version",
    "hash",
    "key_fields",
    "fields",
    "predecessor_id",
    "created_at"
  ],
  "additionalProperties": false
}
```

## ToolSessionWithMcp

Related schemas: [EndUserRef](https://ctx4.me/docs/api-schemas-2.md#enduserref), [SessionTool](https://ctx4.me/docs/api-schemas-3.md#sessiontool).

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "connection_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "user_id": {
      "$ref": "#/components/schemas/EndUserRef"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "expired",
        "revoked"
      ]
    },
    "tools": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SessionTool"
      }
    },
    "disabled_tools": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_.-]{1,239}$"
      }
    },
    "connections": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "connection_id": {
              "type": "string",
              "format": "uuid",
              "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
            },
            "alias": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 64
            }
          },
          "required": [
            "connection_id",
            "alias"
          ],
          "additionalProperties": false
        }
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "max_calls": {
      "type": [
        "integer",
        "null"
      ],
      "exclusiveMinimum": 0
    },
    "calls_used": {
      "type": "integer",
      "minimum": 0
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "mcp_url": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    }
  },
  "required": [
    "id",
    "connection_id",
    "user_id",
    "status",
    "tools",
    "disabled_tools",
    "connections",
    "expires_at",
    "max_calls",
    "calls_used",
    "version",
    "created_at",
    "updated_at",
    "mcp_url"
  ],
  "additionalProperties": false
}
```

## SessionTool


```json
{
  "type": "object",
  "properties": {
    "tool_id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_.-]{1,239}$"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "connector_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "operation_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    }
  },
  "required": [
    "tool_id",
    "connector_id",
    "connector_version",
    "operation_id",
    "connection_id"
  ],
  "additionalProperties": false
}
```

## CreateToolSessionRequest

Related schemas: [EndUserRef](https://ctx4.me/docs/api-schemas-2.md#enduserref).

```json
{
  "type": "object",
  "properties": {
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "user_id": {
      "$ref": "#/components/schemas/EndUserRef"
    },
    "tool_allowlist": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_.-]{1,239}$"
      },
      "minItems": 1,
      "maxItems": 200
    },
    "ttl_seconds": {
      "type": "integer",
      "minimum": 60,
      "maximum": 86400
    },
    "max_calls": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 10000
    }
  },
  "additionalProperties": false,
  "anyOf": [
    {
      "required": [
        "connection_id"
      ]
    },
    {
      "required": [
        "user_id"
      ]
    }
  ],
  "description": "Creates a tool session. With a pinned connection the snapshot derives from connection ∩ catalog ∩ policy ∩ allowlist and is immutable afterwards; without one the session starts empty and fills as accounts are connected to it"
}
```

## ToolSession

Related schemas: [EndUserRef](https://ctx4.me/docs/api-schemas-2.md#enduserref), [SessionTool](https://ctx4.me/docs/api-schemas-3.md#sessiontool).

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "connection_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "user_id": {
      "$ref": "#/components/schemas/EndUserRef"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "expired",
        "revoked"
      ]
    },
    "tools": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SessionTool"
      }
    },
    "disabled_tools": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_.-]{1,239}$"
      }
    },
    "connections": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "connection_id": {
              "type": "string",
              "format": "uuid",
              "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
            },
            "alias": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 64
            }
          },
          "required": [
            "connection_id",
            "alias"
          ],
          "additionalProperties": false
        }
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "max_calls": {
      "type": [
        "integer",
        "null"
      ],
      "exclusiveMinimum": 0
    },
    "calls_used": {
      "type": "integer",
      "minimum": 0
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "connection_id",
    "user_id",
    "status",
    "tools",
    "disabled_tools",
    "connections",
    "expires_at",
    "max_calls",
    "calls_used",
    "version",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

## PatchToolSessionRequest


```json
{
  "type": "object",
  "properties": {
    "expected_version": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "disable": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_.-]{1,239}$"
      },
      "minItems": 1,
      "maxItems": 200
    },
    "enable": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_.-]{1,239}$"
      },
      "minItems": 1,
      "maxItems": 200
    }
  },
  "required": [
    "expected_version"
  ],
  "additionalProperties": false,
  "description": "Bounded session mutation: enable/disable tools within the immutable snapshot, CAS-guarded by expected_version"
}
```

## SessionToolListResponse

Related schemas: [SessionToolDetail](https://ctx4.me/docs/api-schemas-3.md#sessiontooldetail).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SessionToolDetail"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## SessionToolDetail


```json
{
  "type": "object",
  "properties": {
    "tool_id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_.-]{1,239}$"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "connector_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "operation_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "display_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2000
    },
    "input_schema": {}
  },
  "required": [
    "tool_id",
    "connector_id",
    "connector_version",
    "operation_id",
    "connection_id",
    "display_name",
    "description"
  ],
  "additionalProperties": false
}
```

## SyncDeliveryAuthority


```json
{
  "type": "object",
  "properties": {
    "schemaVersion": {
      "type": "number",
      "enum": [
        1
      ]
    },
    "context4OrganizationId": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_-]{1,200}$"
    },
    "workspaceId": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "syncId": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$"
    },
    "resourceKey": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "deliveryGrants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "deliveryGrantId": {
            "type": "string",
            "format": "uuid",
            "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
          },
          "deliveryGeneration": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "retiring",
              "revoked"
            ]
          },
          "retiringExpiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "example": "2026-07-16T12:00:00.000Z"
          },
          "revocationBarriers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "partition": {
                  "type": "integer",
                  "minimum": 0
                },
                "offset": {
                  "type": "string",
                  "pattern": "^(0|[1-9][0-9]{0,18})$"
                }
              },
              "required": [
                "partition",
                "offset"
              ],
              "additionalProperties": false
            },
            "maxItems": 1024
          }
        },
        "required": [
          "deliveryGrantId",
          "deliveryGeneration",
          "state",
          "retiringExpiresAt",
          "revocationBarriers"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 8
    },
    "sourceEpoch": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "sourceEpochTransition": {
      "type": "string",
      "enum": [
        "continuation",
        "replacement-snapshot",
        "incompatible-reset"
      ]
    },
    "authorityRevision": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "active": {
      "type": "boolean"
    }
  },
  "required": [
    "schemaVersion",
    "context4OrganizationId",
    "workspaceId",
    "syncId",
    "entity",
    "resourceKey",
    "deliveryGrants",
    "sourceEpoch",
    "sourceEpochTransition",
    "authorityRevision",
    "active"
  ],
  "additionalProperties": false
}
```

## Sync

Related schemas: [DataSourceAttentionReason](https://ctx4.me/docs/api-schemas-2.md#datasourceattentionreason).

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "connection_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "source_kind": {
      "type": "string",
      "enum": [
        "api_poll",
        "database_cdc",
        "database_poll",
        "topic"
      ]
    },
    "database_poll": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "table": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "columns": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "minItems": 1,
          "maxItems": 256
        },
        "primary_key": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "minItems": 1,
          "maxItems": 16
        },
        "mode": {
          "type": "string",
          "enum": [
            "full_scan",
            "rowversion",
            "timestamp"
          ]
        },
        "watermark_column": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 128
        },
        "full_reconciliation_minutes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10080
        },
        "timestamp_overlap_seconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 86400
        },
        "deletion_policy": {
          "type": "string",
          "enum": [
            "preserve",
            "confirm_missing"
          ]
        },
        "config_revision": {
          "type": "integer",
          "exclusiveMinimum": 0
        }
      },
      "required": [
        "schema",
        "table",
        "columns",
        "primary_key",
        "mode",
        "watermark_column",
        "full_reconciliation_minutes",
        "timestamp_overlap_seconds",
        "deletion_policy",
        "config_revision"
      ],
      "additionalProperties": false
    },
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$"
    },
    "strategy": {
      "type": "string",
      "enum": [
        "incremental",
        "snapshot-diff"
      ]
    },
    "schedule_minutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10080
    },
    "schedule_clamped": {
      "type": "boolean"
    },
    "requested_schedule_minutes": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 10080
    },
    "status": {
      "type": "string",
      "enum": [
        "enabled",
        "paused",
        "deleted"
      ]
    },
    "source_health": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "phase": {
          "type": "string",
          "enum": [
            "gateway_connecting",
            "source_connecting",
            "snapshotting",
            "streaming",
            "paused",
            "failed"
          ]
        },
        "classified_error": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 120
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-07-16T12:00:00.000Z"
        },
        "artifacts": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "state": {
              "type": "string",
              "minLength": 1,
              "maxLength": 16,
              "description": "One of `held`, `released`, `orphaned`, `absent`.",
              "example": "held"
            },
            "since": {
              "type": "string",
              "format": "date-time",
              "example": "2026-07-16T12:00:00.000Z"
            }
          },
          "required": [
            "state",
            "since"
          ],
          "additionalProperties": false,
          "description": "The PostgreSQL replication slot and publication this CDC sync holds on its source, and since when it is in that state: `held`; `released` — the sync stayed paused past the pause limit or failed past the failed-slot grace, so the slot was dropped and the next start takes a fresh snapshot; `orphaned` — a release gave up and the source's DBA must drop the slot; `absent` — nothing was left to release. Null for a source that holds none."
        }
      },
      "required": [
        "phase",
        "classified_error",
        "updated_at",
        "artifacts"
      ],
      "additionalProperties": false
    },
    "source_attention": {
      "$ref": "#/components/schemas/DataSourceAttentionReason"
    },
    "last_run_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "next_run_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "connector_id",
    "connection_id",
    "source_kind",
    "entity",
    "strategy",
    "schedule_minutes",
    "schedule_clamped",
    "requested_schedule_minutes",
    "status",
    "source_health",
    "last_run_at",
    "next_run_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

## SyncList

Related schemas: [Sync](https://ctx4.me/docs/api-schemas-3.md#sync).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Sync"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## SyncTestFire


```json
{
  "type": "object",
  "properties": {
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "external_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "payload": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "external_id",
          "payload"
        ],
        "additionalProperties": false
      }
    },
    "estimated_total": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    }
  },
  "required": [
    "records",
    "estimated_total"
  ],
  "additionalProperties": false
}
```

## SyncRunList

Related schemas: [SyncRun](https://ctx4.me/docs/api-schemas-4.md#syncrun).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SyncRun"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

---

# API schemas: part 4

Source: https://ctx4.me/docs/api-schemas-4

Exact field names, required, enum, nullable and constraints are preserved from [OpenAPI](https://ctx4.me/docs/openapi.json). `$ref` resolves relative to `components.schemas` in the full document. All parts: [1](https://ctx4.me/docs/api-schemas-1.md), [2](https://ctx4.me/docs/api-schemas-2.md), [3](https://ctx4.me/docs/api-schemas-3.md), [4](https://ctx4.me/docs/api-schemas-4.md).

## SyncRun


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "sync_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "kind": {
      "type": "string",
      "enum": [
        "backfill",
        "incremental",
        "manual"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "planned",
        "running",
        "deferred",
        "completed",
        "failed"
      ]
    },
    "fetched": {
      "type": "integer",
      "minimum": 0
    },
    "created": {
      "type": "integer",
      "minimum": 0
    },
    "updated": {
      "type": "integer",
      "minimum": 0
    },
    "deleted": {
      "type": "integer",
      "minimum": 0
    },
    "error_code": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 120
    },
    "backoff_reason": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 200
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "duration_ms": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "id",
    "sync_id",
    "kind",
    "status",
    "fetched",
    "created",
    "updated",
    "deleted",
    "error_code",
    "backoff_reason",
    "started_at",
    "completed_at",
    "duration_ms",
    "created_at"
  ],
  "additionalProperties": false
}
```

## SyncRecordList

Related schemas: [SyncRecord](https://ctx4.me/docs/api-schemas-4.md#syncrecord).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SyncRecord"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## SyncRecord


```json
{
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$"
    },
    "change_type": {
      "type": "string",
      "enum": [
        "created",
        "updated",
        "deleted"
      ]
    },
    "mod_cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "payload": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": {}
    },
    "run_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "recorded_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    }
  },
  "required": [
    "external_id",
    "entity",
    "change_type",
    "mod_cursor",
    "payload",
    "run_id",
    "recorded_at"
  ],
  "additionalProperties": false
}
```

## SyncReplay


```json
{
  "type": "object",
  "properties": {
    "replayed": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "replayed"
  ],
  "additionalProperties": false
}
```

## SyncableEntityList


```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "strategy": {
            "type": "string",
            "enum": [
              "incremental",
              "snapshot-diff"
            ]
          },
          "default_schedule_minutes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10080
          }
        },
        "required": [
          "key",
          "title",
          "strategy",
          "default_schedule_minutes"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false
}
```

## SyncDeliveryCapabilities


```json
{
  "type": "object",
  "properties": {
    "channel_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "envelope_schema_versions": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "minItems": 1
    },
    "max_payload_bytes": {
      "type": "integer",
      "minimum": 1
    },
    "max_envelope_bytes": {
      "type": "integer",
      "minimum": 1
    },
    "max_key_bytes": {
      "type": "integer",
      "minimum": 1
    },
    "payload_measurement": {
      "type": "string",
      "enum": [
        "utf8-json"
      ]
    },
    "delete_semantics": {
      "type": "string",
      "enum": [
        "logical-delete-null-payload",
        "two-step-logical-delete-then-tombstone"
      ]
    },
    "retraction": {
      "type": "object",
      "properties": {
        "header": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "marker": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "grace_ms": {
          "type": "integer",
          "minimum": 1
        },
        "min_compaction_lag_ms": {
          "type": "integer",
          "minimum": 1
        },
        "delete_retention_ms": {
          "type": "integer",
          "minimum": 1
        }
      },
      "required": [
        "header",
        "marker",
        "grace_ms",
        "min_compaction_lag_ms",
        "delete_retention_ms"
      ],
      "additionalProperties": false
    },
    "oversized_record_code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    }
  },
  "required": [
    "channel_version",
    "envelope_schema_versions",
    "max_payload_bytes",
    "max_envelope_bytes",
    "max_key_bytes",
    "payload_measurement",
    "delete_semantics",
    "retraction",
    "oversized_record_code"
  ],
  "additionalProperties": false
}
```

## SyncExportSession


```json
{
  "type": "object",
  "properties": {
    "export_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "organization_id": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_-]{1,200}$"
    },
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "schema_fingerprint": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^sha256:[a-f0-9]{64}$"
    },
    "expires_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z"
    },
    "range": {
      "type": "object",
      "properties": {
        "after_cursor": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^(0|[1-9][0-9]{0,18})$"
        },
        "through_cursor": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,18})$"
        }
      },
      "required": [
        "after_cursor",
        "through_cursor"
      ],
      "additionalProperties": false
    },
    "sync_id": {
      "type": "string",
      "format": "uuid",
      "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
    },
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$"
    },
    "state": {
      "type": "string",
      "enum": [
        "preparing",
        "running",
        "complete",
        "range_expired",
        "archive_unavailable",
        "digest_mismatch",
        "cancelled",
        "failed"
      ]
    },
    "frontier": {
      "type": "object",
      "properties": {
        "mod_cursor": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20
        },
        "captured_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-07-16T12:00:00.000Z"
        },
        "source_epoch": {
          "type": "string",
          "format": "uuid",
          "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"
        }
      },
      "required": [
        "mod_cursor",
        "captured_at",
        "source_epoch"
      ],
      "additionalProperties": false
    },
    "publication_barrier": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "partition": {
            "type": "integer",
            "minimum": 0
          },
          "offset": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20
          }
        },
        "required": [
          "partition",
          "offset"
        ],
        "additionalProperties": false
      }
    },
    "publication_channel": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,248}$"
    },
    "progress": {
      "type": "object",
      "properties": {
        "records": {
          "type": "integer",
          "minimum": 0
        },
        "encoded_bytes": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "records",
        "encoded_bytes"
      ],
      "additionalProperties": false
    },
    "record_count": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "digest": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 71
    },
    "terminal_reason": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 200
    },
    "delivery": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "bounded-replay-topic"
          ]
        },
        "channel": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,248}$"
        },
        "export_key": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "delivery_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "state": {
          "type": "string",
          "enum": [
            "pending",
            "publishing",
            "complete",
            "failed",
            "cancelled"
          ]
        },
        "records": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$"
        },
        "terminal_positions": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "properties": {
              "partition": {
                "type": "integer",
                "minimum": 0
              },
              "offset": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$"
              }
            },
            "required": [
              "partition",
              "offset"
            ],
            "additionalProperties": false
          },
          "minItems": 1
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "example": "2026-07-16T12:00:00.000Z"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-07-16T12:00:00.000Z"
        },
        "error": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 200
        }
      },
      "required": [
        "kind",
        "channel",
        "export_key",
        "delivery_generation",
        "state",
        "records",
        "terminal_positions",
        "completed_at",
        "updated_at",
        "error"
      ],
      "additionalProperties": false
    },
    "parts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "after_cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20
          },
          "through_cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20
          },
          "records": {
            "type": "integer",
            "minimum": 1
          },
          "encoded_bytes": {
            "type": "integer",
            "minimum": 1
          },
          "digest": {
            "type": "string",
            "minLength": 1,
            "maxLength": 71
          },
          "download_url": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 4096
          }
        },
        "required": [
          "index",
          "after_cursor",
          "through_cursor",
          "records",
          "encoded_bytes",
          "digest",
          "download_url"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "export_id",
    "sync_id",
    "entity",
    "state",
    "frontier",
    "publication_barrier",
    "progress",
    "record_count",
    "digest",
    "terminal_reason",
    "parts"
  ],
  "additionalProperties": false
}
```

## SyncProviderListResponse


```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
            "example": "bitrix24"
          },
          "display_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        },
        "required": [
          "key",
          "display_name"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## EndpointListResponse

Related schemas: [EndpointSummary](https://ctx4.me/docs/api-schemas-4.md#endpointsummary).

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/EndpointSummary"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 400,
      "description": "Cursor for the next page; null when exhausted"
    }
  },
  "required": [
    "data",
    "next_cursor"
  ],
  "additionalProperties": false
}
```

## EndpointSummary


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^(?:GET|POST|PUT|PATCH|DELETE|HEAD) \\/[\\x21-\\x7e]{0,240}$",
      "example": "GET /api/v4/leads/{id}"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "group": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "The vendor's own grouping of the endpoint (its spec tag or resource)",
      "example": "leads"
    },
    "method": {
      "type": "string",
      "enum": [
        "GET",
        "POST",
        "PUT",
        "PATCH",
        "DELETE",
        "HEAD"
      ]
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "pattern": "^\\/",
      "example": "/api/v4/leads/{id}"
    },
    "summary": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2000
    },
    "call_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 600,
      "description": "The mirror URL that calls this endpoint: `/v1/api/{connectorId}` followed by the vendor path",
      "example": "/v1/api/amocrm/api/v4/leads/{id}"
    },
    "risk": {
      "type": "string",
      "enum": [
        "read",
        "write",
        "destructive",
        "external_send"
      ],
      "description": "What calling it does to the world, as a floor: read, write, destructive or external_send (reaches a person outside the vendor)"
    },
    "sensitive": {
      "type": "boolean",
      "description": "Its schemas name credentials or personal data (a floor)"
    },
    "idempotent": {
      "type": "boolean"
    },
    "paging_kind": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "page",
        "offset",
        "cursor",
        "next-link",
        "header-cursor",
        "rpc-start",
        "relay",
        null
      ],
      "description": "How a listing pages, or null when pages cannot be collected from it"
    },
    "descriptor_digest": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{64}$",
      "description": "sha256 of the endpoint's contract (method, path, schemas, risk, idempotency — not its paging or summary); null only for a row seeded before descriptors existed",
      "example": "089fed2ebbff74aa8cd059e02cedb06f5fa5044a8e86ff7b457e75a90b8341fa"
    },
    "removed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z",
      "description": "When a lock regeneration dropped the endpoint; null while it is live. A removed endpoint is listed only with `include_removed=true`"
    }
  },
  "required": [
    "id",
    "connector_id",
    "group",
    "method",
    "path",
    "summary",
    "call_url"
  ],
  "additionalProperties": false
}
```

## EndpointDetail

Related schemas: [PagingDescriptor](https://ctx4.me/docs/api-schemas-4.md#pagingdescriptor).

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^(?:GET|POST|PUT|PATCH|DELETE|HEAD) \\/[\\x21-\\x7e]{0,240}$",
      "example": "GET /api/v4/leads/{id}"
    },
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "group": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "The vendor's own grouping of the endpoint (its spec tag or resource)",
      "example": "leads"
    },
    "method": {
      "type": "string",
      "enum": [
        "GET",
        "POST",
        "PUT",
        "PATCH",
        "DELETE",
        "HEAD"
      ]
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "pattern": "^\\/",
      "example": "/api/v4/leads/{id}"
    },
    "summary": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2000
    },
    "call_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 600,
      "description": "The mirror URL that calls this endpoint: `/v1/api/{connectorId}` followed by the vendor path",
      "example": "/v1/api/amocrm/api/v4/leads/{id}"
    },
    "risk": {
      "type": "string",
      "enum": [
        "read",
        "write",
        "destructive",
        "external_send"
      ],
      "description": "What calling it does to the world, as a floor: read, write, destructive or external_send (reaches a person outside the vendor)"
    },
    "sensitive": {
      "type": "boolean",
      "description": "Its schemas name credentials or personal data (a floor)"
    },
    "idempotent": {
      "type": "boolean"
    },
    "paging_kind": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "page",
        "offset",
        "cursor",
        "next-link",
        "header-cursor",
        "rpc-start",
        "relay",
        null
      ],
      "description": "How a listing pages, or null when pages cannot be collected from it"
    },
    "descriptor_digest": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{64}$",
      "description": "sha256 of the endpoint's contract (method, path, schemas, risk, idempotency — not its paging or summary); null only for a row seeded before descriptors existed",
      "example": "089fed2ebbff74aa8cd059e02cedb06f5fa5044a8e86ff7b457e75a90b8341fa"
    },
    "removed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-07-16T12:00:00.000Z",
      "description": "When a lock regeneration dropped the endpoint; null while it is live. A removed endpoint is listed only with `include_removed=true`"
    },
    "input_schema": {
      "description": "JSON Schema of the call input: an object with optional `path`, `query`, `header` and `body` members, self-contained (`$defs` included)"
    },
    "output_schema": {},
    "paging": {
      "$ref": "#/components/schemas/PagingDescriptor"
    }
  },
  "required": [
    "id",
    "connector_id",
    "group",
    "method",
    "path",
    "summary",
    "call_url"
  ],
  "additionalProperties": false,
  "description": "One raw endpoint with its input and (when published) output schema, and its paging descriptor"
}
```

## PagingDescriptor


```json
{
  "type": [
    "object",
    "null"
  ],
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "page",
        "offset",
        "cursor",
        "next-link",
        "header-cursor",
        "rpc-start",
        "relay"
      ]
    },
    "records": {
      "type": "string",
      "maxLength": 500,
      "description": "Pointer to the records array in the output; `\"\"` is the whole document",
      "example": "/_embedded/leads"
    },
    "max_page_size": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "inputs": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 500,
        "description": "RFC 6901 JSON pointer into the endpoint's input or output document",
        "example": "/query/page"
      },
      "description": "Input pointers by role: page, size, cursor, offset, start, first, after"
    },
    "next": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      },
      "description": "Where the next page is named: output pointers by role (link, cursor, end_cursor, has_next_page) or `header`, a response header name"
    }
  },
  "required": [
    "kind",
    "records",
    "max_page_size",
    "inputs"
  ],
  "additionalProperties": false
}
```

## ConnectorOpenApiDocument


```json
{
  "type": "object",
  "properties": {
    "openapi": {
      "type": "string",
      "enum": [
        "3.1.0"
      ]
    },
    "info": {
      "type": "object",
      "additionalProperties": {}
    },
    "servers": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "paths": {
      "type": "object",
      "additionalProperties": {}
    },
    "components": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "openapi",
    "info",
    "servers",
    "paths",
    "components"
  ],
  "additionalProperties": {}
}
```

## EndpointSearchResponse

Related schemas: [EndpointSearchItem](https://ctx4.me/docs/api-schemas-4.md#endpointsearchitem).

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/EndpointSearchItem"
      }
    },
    "scope": {
      "type": "object",
      "properties": {
        "connectors": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
            "example": "bitrix24"
          },
          "description": "The connectors the search ran over: those of the caller's usable connections, narrowed by `connectors`. Empty when nothing is usable — then `items` is empty too, never an error"
        },
        "index": {
          "type": "string",
          "enum": [
            "ratel",
            "ilike"
          ]
        }
      },
      "required": [
        "connectors",
        "index"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "items",
    "scope"
  ],
  "additionalProperties": false
}
```

## EndpointSearchItem


```json
{
  "type": "object",
  "properties": {
    "connector_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
      "example": "bitrix24"
    },
    "endpoint_id": {
      "type": "string",
      "pattern": "^(?:GET|POST|PUT|PATCH|DELETE|HEAD) \\/[\\x21-\\x7e]{0,240}$",
      "example": "GET /api/v4/leads/{id}"
    },
    "method": {
      "type": "string",
      "enum": [
        "GET",
        "POST",
        "PUT",
        "PATCH",
        "DELETE",
        "HEAD"
      ]
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "pattern": "^\\/",
      "example": "/api/v4/leads/{id}"
    },
    "summary": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2000
    },
    "group": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "risk": {
      "type": "string",
      "enum": [
        "read",
        "write",
        "destructive",
        "external_send"
      ]
    },
    "sensitive": {
      "type": "boolean"
    },
    "idempotent": {
      "type": "boolean"
    },
    "paging_kind": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "page",
        "offset",
        "cursor",
        "next-link",
        "header-cursor",
        "rpc-start",
        "relay",
        null
      ]
    },
    "descriptor_digest": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{64}$",
      "description": "sha256 of the endpoint's contract (method, path, schemas, risk, idempotency — not its paging or summary); null only for a row seeded before descriptors existed",
      "example": "089fed2ebbff74aa8cd059e02cedb06f5fa5044a8e86ff7b457e75a90b8341fa"
    },
    "score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Relevance relative to the best hit of this answer: the top hit is 1, the rest in (0, 1]; a fallback answer scores every hit 1"
    }
  },
  "required": [
    "connector_id",
    "endpoint_id",
    "method",
    "path",
    "summary",
    "group",
    "risk",
    "sensitive",
    "idempotent",
    "paging_kind",
    "descriptor_digest",
    "score"
  ],
  "additionalProperties": false
}
```

## EndpointSearchRequest


```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Free text, Russian or English",
      "example": "list the labels of a repository"
    },
    "connectors": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9-]{1,78}$",
        "example": "bitrix24"
      },
      "maxItems": 50,
      "description": "Narrows the scope to these connectors; a connector the caller has no usable connection for is dropped, never added"
    },
    "borrowers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256
      },
      "maxItems": 200,
      "description": "The principals whose connections this search may use (exact `end_user_ref` match, never widened). Omitted: every active connection of the API key's workspace",
      "example": [
        "ws_a1b2c3:u_d4e5f6",
        "ws_a1b2c3:a_workspace"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

---

# API schemas: part 5

Source: https://ctx4.me/docs/api-schemas-5

Exact field names, required, enum, nullable and constraints are preserved from [OpenAPI](https://ctx4.me/docs/openapi.json). `$ref` resolves relative to `components.schemas` in the full document. All parts: [1](https://ctx4.me/docs/api-schemas-1.md), [2](https://ctx4.me/docs/api-schemas-2.md), [3](https://ctx4.me/docs/api-schemas-3.md), [4](https://ctx4.me/docs/api-schemas-4.md).

## ConnectorApiBody


```json
{}
```