Technical documentation

Executions.

Create, inspect and cancel Context4 tool executions: API requests, responses, attempts and errors.

Generated from the public Context4 OpenAPI. Authenticate with Authorization: Bearer and an API key. General rules: API. Full contract: 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	{"type":"string"} Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome

Request body

Required. CreateExecutionRequest

Data

{
  "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
400	Problem (validation_failed)	`application/problem+json` Problem
401	Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)	`application/problem+json` Problem
403	Problem (capability_missing, forbidden, session_expired, session_revoked, session_call_budget_exhausted)	`application/problem+json` Problem
404	Problem (not_found)	`application/problem+json` Problem
409	Problem (idempotency_conflict)	`application/problem+json` Problem
429	Problem (rate_limited)	`application/problem+json` Problem
500	Problem (internal)	`application/problem+json` Problem
503	Problem (service_unavailable)	`application/problem+json` Problem

Successful response headers:

Data

{
  "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	{"type":"string","enum":["requested","queued","running","retrying","succeeded","failed","rejected","cancelled"]}
`connector_id`	query	no	{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,78}$","example":"bitrix24"}
`user_id`	query	no	{"$ref":"#/components/schemas/ExecutionEndUserRef"}
`from`	query	no	{"type":"string","format":"date-time","example":"2026-07-16T12:00:00.000Z"}
`to`	query	no	{"type":"string","format":"date-time","example":"2026-07-16T12:00:00.000Z"}
`cursor`	query	no	{"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"} Opaque pagination cursor from a previous response
`limit`	query	no	{"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"} Page size (1-100, default 20)

Responses and errors

HTTP	Meaning	Format and schema
200	Executions ordered by creation time (descending)	`application/json` ExecutionListResponse
400	Problem (validation_failed)	`application/problem+json` Problem
401	Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)	`application/problem+json` Problem
403	Problem (capability_missing)	`application/problem+json` Problem
429	Problem (rate_limited)	`application/problem+json` Problem
500	Problem (internal)	`application/problem+json` Problem
503	Problem (service_unavailable)	`application/problem+json` Problem

Successful response headers:

Data

{
  "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	{"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"}

Responses and errors

HTTP	Meaning	Format and schema
200	Execution view; terminal successes include the result	`application/json` ExecutionWithResult
400	Problem (validation_failed)	`application/problem+json` Problem
401	Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)	`application/problem+json` Problem
403	Problem (capability_missing)	`application/problem+json` Problem
404	Problem (not_found)	`application/problem+json` Problem
429	Problem (rate_limited)	`application/problem+json` Problem
500	Problem (internal)	`application/problem+json` Problem
503	Problem (service_unavailable)	`application/problem+json` Problem

Successful response headers:

Data

{
  "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	{"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"}

Responses and errors

HTTP	Meaning	Format and schema
200	Append-only attempt records	`application/json` AttemptListResponse
400	Problem (validation_failed)	`application/problem+json` Problem
401	Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)	`application/problem+json` Problem
403	Problem (capability_missing)	`application/problem+json` Problem
404	Problem (not_found)	`application/problem+json` Problem
429	Problem (rate_limited)	`application/problem+json` Problem
500	Problem (internal)	`application/problem+json` Problem
503	Problem (service_unavailable)	`application/problem+json` Problem

Successful response headers:

Data

{
  "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	{"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"}

Request body

Required. CancelExecutionRequest

Data

{
  "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
400	Problem (validation_failed)	`application/problem+json` Problem
401	Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)	`application/problem+json` Problem
403	Problem (capability_missing)	`application/problem+json` Problem
404	Problem (not_found)	`application/problem+json` Problem
409	Problem (conflict, execution_not_cancellable)	`application/problem+json` Problem
429	Problem (rate_limited)	`application/problem+json` Problem
500	Problem (internal)	`application/problem+json` Problem
503	Problem (service_unavailable)	`application/problem+json` Problem

Successful response headers:

Data

{
  "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"
    }
  }
}