---
title: "API schemas: part 1"
description: "API input and response JSON Schema: Problem — Connection. Fields, required properties and API constraints."
group: "Technical documentation"
order: 45
---

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


# API schemas: part 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
}
```