v1.0.0OAS 3.1.0

codecloud API

The codecloud API runs fully managed, sandboxed coding agents — Claude Code, Codex, or OpenCode — against your GitHub repositories.

Contact: codecloud support

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer API_KEY

You can generate an API key from your dashboard.

Agent runtimes

Each run executes one official coding agent in an isolated sandbox. Set agent_provider when you create a run, or omit it to use the default runtime on your account.

Runtime	`agent_provider`	Authentication
Claude Code	`claude-code`	Anthropic API key, Amazon Bedrock, or a Claude Pro / Max / Team / Enterprise subscription
Codex	`codex`	OpenAI API key or a ChatGPT subscription
OpenCode	`opencode` (default)	Provider API keys (Anthropic, OpenAI, Google, and others)

Subscriptions

Claude Code and Codex can use the subscription you already pay for instead of a provider API key. Connect credentials once in the dashboard:

Claude Code: on a trusted machine run claude setup-token, then paste the token into the Claude subscription control.
Codex: click Connect ChatGPT, open the official OpenAI device-login URL, and enter the one-time code. Codecloud restores the refreshed credential cache on each Codex run.

When creating a run, pass agent_auth_method as subscription or api-key. If omitted, Codecloud uses the method saved on your account.

{
  "repo": "your-org/your-repo",
  "agent_provider": "claude-code",
  "agent_auth_method": "subscription",
  "prompt": "Fix the failing tests in src/utils"
}

Subscription credentials are encrypted at rest with the same AES-256-GCM protection as API keys. Codex subscription runs are serialized per user so the refresh-token cache can be restored and saved as one lifecycle.

Runtime notes:

Claude Code accepts anthropic and amazon-bedrock providers only.
Codex accepts openai only.
Custom HTTP tools are supported on OpenCode only.
Scheduled runs use your account's default runtime.

Rate Limits

Starter plan: 1 concurrent agent
Pro plan: 5 concurrent agents

Webhooks

You can optionally provide a webhook_url when creating a run. When the run completes (success or failure), we'll send a POST request to your URL with the run details.

Headers sent with every webhook:

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`codecloud-Webhooks/1.0`
`X-Codecloud-Event`	Event type: `agent.completed`, `agent.failed`, or `agent.progress`
`X-Codecloud-Delivery`	Unique delivery ID for this attempt
`X-Codecloud-Signature`	HMAC SHA-256 hex digest (only if webhook secret is configured)

Example payload:

{
  "event": "agent.completed",
  "run_id": "jd7x8k9m2n3p4q5r",
  "status": "completed",
  "mode": "execute",
  "repo": "owner/repo",
  "result": "I've added JWT-based authentication...",
  "pr": {
    "url": "https://github.com/owner/repo/pull/42",
    "number": 42,
    "branch": "codecloud/add-auth"
  },
  "usage": {
    "input_tokens": 12500,
    "output_tokens": 3200
  },
  "created_at": "2025-01-16T12:00:00.000Z",
  "completed_at": "2025-01-16T12:05:00.000Z"
}

Payload fields:

Field	Type	Description
`event`	string	`agent.completed` or `agent.failed`
`run_id`	string	The agent run ID
`status`	string	`completed` or `failed`
`mode`	string	`execute` or `plan`
`repo`	string?	Repository in `owner/repo` format; absent for `blank_workspace` runs
`result`	string?	Agent output (execute mode, completed)
`plan`	string?	Agent plan (plan mode, completed)
`error`	string?	Error message (when failed)
`pr`	object?	PR info, present if a PR was created
`pr.url`	string	PR URL
`pr.number`	number	PR number
`pr.branch`	string	Branch name
`usage`	object?	Token usage, present when available
`usage.input_tokens`	number	Input tokens consumed
`usage.output_tokens`	number	Output tokens generated
`created_at`	string	ISO 8601 timestamp
`completed_at`	string?	ISO 8601 timestamp

Signature verification:

If you have a webhook secret configured, verify the X-Codecloud-Signature header by computing the HMAC SHA-256 hex digest of the raw request body using your secret:

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex');
const isValid = signature === req.headers['x-codecloud-signature'];

Retries: Failed deliveries are retried up to 3 times with delays of 1s, 5s, and 30s.

Progress Events

When enabled in your dashboard, agent.progress webhooks are sent while the agent is running, delivering current agent output plus key heartbeat/status updates (relay connected, tool starts, retries, etc.). These are fire-and-forget (no retries, no delivery records). The run must include a webhook_url.

Text delta:

{
  "event": "agent.progress",
  "run_id": "jd7x8k9m2n3p4q5r",
  "status": "running",
  "thinking": "Currently analyzing the authentication flow and..."
}

Tool call:

{
  "event": "agent.progress",
  "run_id": "jd7x8k9m2n3p4q5r",
  "status": "running",
  "tool_call": {
    "name": "bash",
    "arguments": { "command": "ls -la" },
    "status": "running"
  }
}

Field	Type	Description
`event`	string	Always `agent.progress`
`run_id`	string	The agent run ID
`status`	string	Always `running`
`thinking`	string?	Current agent output (present for text deltas)
`tool_call`	object?	Tool call info (present when agent invokes a tool). Contains `name`, `arguments`, and `status` (`"pending"`, `"running"`, `"completed"`, `"error"`)

Schedules

Schedules let you run agents automatically, either once at a future time or recurring on a cron schedule.

Creating a schedule

Recurring (every 6 hours):

{
  "type": "recurring",
  "cron": "0 */6 * * *",
  "prompt": "Run the test suite and fix any failures",
  "repo": "owner/repo",
  "auto_create_pr": true
}

One-time (run at a specific time):

{
  "type": "once",
  "run_at": "2025-03-01T09:00:00Z",
  "prompt": "Deploy the new feature branch",
  "repo": "owner/repo"
}

Cron syntax

Standard 5-field cron expressions (minute, hour, day-of-month, month, day-of-week):

Expression	Description
`0 /6 * *`	Every 6 hours
`0 9 * * MON-FRI`	Weekdays at 9 AM
`30 2 * * *`	Daily at 2:30 AM
`0 0 1 * *`	First of every month at midnight
`0 9 * * 1`	Every Monday at 9 AM

Minimum interval between runs is 15 minutes (e.g. */15 * * * * is the fastest allowed).

How it works

Each schedule creates independent agent runs at the configured cron schedule
The same prompt is used for every execution
Runs created by a schedule include a schedule_id field so you can trace them back
Use GET /api/v1/schedules/{id} to check total_runs, total_skips, next_run_at, and last_run_id
Delete a schedule to stop future runs (in-progress runs are not affected)

Skipped runs

When a schedule fires but your concurrent or monthly run limit is reached, the run is skipped (not queued). The schedule continues firing at the next interval. Skipped runs are tracked in total_skips and trigger a schedule.run.skipped webhook.

Plan changes

If you downgrade to the free plan, all active schedules are automatically deleted and a schedule.deleted webhook is sent. Runs already in progress are not affected.

Schedule webhook events

If you provide a webhook_url when creating a schedule, you'll receive these events:

Event	When
`schedule.run.executed`	A scheduled run was created successfully
`schedule.run.skipped`	A scheduled run was skipped due to limits
`schedule.deleted`	Schedule was auto-deleted (e.g., plan downgrade)

These are in addition to the standard agent.completed / agent.failed webhooks for each run.

Example schedule.run.skipped payload:

{
  "event": "schedule.run.skipped",
  "schedule_id": "abc123",
  "reason": "concurrent_limit",
  "next_run_at": "2025-02-16T00:00:00.000Z",
  "total_skips": 3,
  "created_at": "2025-02-15T18:00:00.000Z"
}

Example schedule.run.executed payload:

{
  "event": "schedule.run.executed",
  "schedule_id": "abc123",
  "run_id": "def456",
  "next_run_at": "2025-02-16T00:00:00.000Z",
  "created_at": "2025-02-15T18:00:00.000Z"
}

Agent Runs

Create and manage Claude Code, Codex, and OpenCode runs on your repositories

POST/api/v1/agents

Create a new agent run

Queue a Claude Code, Codex, or OpenCode agent to execute a task on your GitHub repository. Set agent_provider to choose the runtime and agent_auth_method to use a connected Claude / ChatGPT subscription or a provider API key.

Request Body

repostring

GitHub repository in format: owner/repo. If not specified, uses your default repository.

Example: "username/repo-name"

promptstringrequired

The instruction/task for the AI agent to execute

Example: "Add a new endpoint to handle user authentication"

system_promptstring

Optional replacement for the OpenCode system prompt. If provided, this prompt is sent as the full system prompt for the run instead of Codecloud's default.

Example: "You are a concise repository assistant. Follow the user prompt exactly."

modelstring

AI model to use. If not specified, uses your default model. Claude Code requires an Anthropic or Bedrock model; Codex requires an OpenAI model.

Example: "claude-opus-4.5"

providerstring

AI provider. If not specified, uses your default provider. Claude Code supports anthropic and amazon-bedrock; Codex supports openai.

Example: "anthropic"

branchstring

Git branch to use (defaults to repo's default branch)

Example: "main"

webhook_urlstring

URL to receive webhook notifications when the run completes

Example: "https://example.com/webhooks/agent-complete"

mode"execute" | "plan"

Run mode: 'execute' runs the agent normally, 'plan' returns a plan without making changes

Example: "execute"

auto_create_prboolean

If true, automatically create a GitHub PR with the agent's changes after completion

Example: true

blank_workspaceboolean

If true, the agent runs in a blank workspace with no repository. The repo, branch, and auto_create_pr fields are ignored. No code will be read or written — use this for tool-only workflows, Q&A, or other non-code tasks.

agent_provider"opencode" | "claude-code" | "codex"

Agent runtime: 'claude-code' (Anthropic CLI), 'codex' (OpenAI CLI), or 'opencode' (default). If omitted, uses your default runtime.

Example: "claude-code"

agent_auth_method"subscription" | "api-key"

For Claude Code or Codex: 'subscription' uses a connected Claude or ChatGPT subscription; 'api-key' uses a provider key. If omitted, uses the method saved on your account.

Example: "subscription"

toolsToolDefinition[]

External HTTP tools the agent can call during execution. Supported on OpenCode only. Each tool defines its own endpoint and auth headers.

Array items:

namestringrequired

Tool name (used as identifier)

Example: "search_inventory"

descriptionstringrequired

What the tool does

Example: "Search product inventory"

parametersobjectrequired

Tool parameters in JSON Schema format

propertiesobjectrequired

Parameter definitions keyed by name

Example: {"query":{"type":"string","description":"Search query"},"limit":{"type":"number","description":"Max results"}}

requiredstring[]

Required parameter names

endpointobjectrequired

urlstringrequired

The HTTP endpoint URL to call (must be a public URL, no localhost or private IPs)

Example: "https://api.example.com/search"

method"GET" | "POST" | "PUT" | "PATCH" | "DELETE"required

HTTP method

Example: "POST"

headersobject

Custom headers to include (e.g. Authorization, API keys)

Example: {"Authorization":"Bearer token-abc"}

agentsobject[]

Subagent definitions available to the parent agent during execution. Each subagent has a focused prompt and tool subset.

Array items:

namestringrequired

descriptionstringrequired

mode"subagent"required

promptstringrequired

toolsobjectrequired

max_turnsinteger

Responses

201Agent run created successfully

idstringrequired

Unique identifier for the agent run

titlestring

Auto-generated run title

status"queued"required

Initial status of a new run

messagestringrequired

Success message

Errors(3)

400Validation error or bad request

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

401Invalid or missing API key

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

500Internal server error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

GET/api/v1/agents

List agent runs

Retrieve a list of your agent runs, optionally filtered by status.

Query Parameters

limit

integer

Maximum number of runs to return (1-100)

status

"queued" | "running" | "completed" | "failed"

Filter by run status

Responses

200List of agent runs

runsRunSummary[]required

Array items:

idstringrequired

Unique identifier for the agent run

titlestring

Auto-generated run title

status"queued" | "running" | "completed" | "failed"required

Current status of the agent run

modelstring

Model used for this run

Example: "claude-sonnet-4-5"

providerstring

Provider used for this run

Example: "anthropic"

repostring

GitHub repository in format: owner/repo, or absent for blank_workspace runs

createdAtstringrequired

ISO 8601 timestamp when the run was created

Example: "2025-01-16T12:00:00.000Z"

completedAtstring

ISO 8601 timestamp when the run completed

Errors(3)

400Validation error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

401Invalid or missing API key

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

500Internal server error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

GET/api/v1/agents/run/{id}

Get agent run details

Retrieve the details and status of a specific agent run.

Path Parameters

id

stringrequired

Unique identifier for the agent run

Responses

200Agent run details

idstringrequired

Unique identifier for the agent run

titlestring

Auto-generated run title

status"queued" | "running" | "completed" | "failed"required

Current status of the agent run

mode"execute" | "plan"

Run mode ('execute' or 'plan')

modelstring

Model used for this run

Example: "claude-sonnet-4-5"

providerstring

Provider used for this run

Example: "anthropic"

resultstring

The agent's output (only present when status is 'completed')

planstring

The agent's plan (only present when mode is 'plan' and status is 'completed')

errorstring

Error message (only present when status is 'failed')

repostring

GitHub repository in format: owner/repo, or absent for blank_workspace runs

promptstringrequired

The instruction/task for the AI agent

pr_urlstring

URL of the created PR (only present if auto_create_pr was true and PR was created)

Example: "https://github.com/owner/repo/pull/123"

pr_numbernumber

Number of the created PR (only present if auto_create_pr was true and PR was created)

Example: 123

prsobject[]required

All pull requests created by this run (supports multiple PRs per run)

Array items:

urlstringrequired

Full URL of the PR

numbernumberrequired

PR number

branchstringrequired

Branch name used for the PR

repostringrequired

Repository in format: owner/repo

titlestring

PR title

input_tokensnumber

Input tokens used

output_tokensnumber

Output tokens used (estimated while running)

schedule_idstring

ID of the schedule that created this run (if applicable)

createdAtstringrequired

ISO 8601 timestamp when the run was created

Example: "2025-01-16T12:00:00.000Z"

startedAtstring

ISO 8601 timestamp when the run started executing

completedAtstring

ISO 8601 timestamp when the run completed

Errors(4)

400Invalid run ID format

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

401Invalid or missing API key

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

404Run not found

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

500Internal server error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

POST/api/v1/agents/run/{id}/message

Send a follow-up message to an agent run

Resume an existing agent run by sending a follow-up prompt.

This endpoint is asynchronous - it schedules the follow-up and returns immediately. Results will be sent via webhook (if configured) when complete. Use the GET endpoint to poll for status.

Requirements:

The original run must have status "completed"

Options:

mode: Override the run mode ('execute' or 'plan')
update_pr: If true, commits and pushes changes to the existing PR branch
idempotency_key: Unique key to ensure idempotency (useful for retries)

Idempotency: To safely handle retries, include an idempotency_key in the request body or an Idempotency-Key header. If a request with the same key was already processed, the same response is returned without re-processing. Keys expire after 24 hours.

Path Parameters

id

stringrequired

Unique identifier for the agent run

Request Body

promptstringrequired

The follow-up instruction/task for the AI agent to execute in the existing session

Example: "Now add unit tests for the authentication endpoint"

system_promptstring

Optional replacement for the OpenCode system prompt on this run and future follow-ups.

Example: "Continue as a concise repository assistant. Follow the user prompt exactly."

mode"execute" | "plan"

Run mode for this follow-up: 'execute' runs the agent normally, 'plan' returns a plan without making changes. Defaults to the original run's mode.

Example: "execute"

update_prboolean

If true, push changes to the existing PR branch (or create a new PR if none exists). Only valid for execute mode.

Example: true

idempotency_keystring

Optional unique key to ensure exactly-once processing. If a request with this key was already processed, the same response is returned. Keys expire after 24 hours.

Example: "msg-12345-abc"

toolsToolDefinition[]

External HTTP tools the agent can call during execution. Overrides tools from the original run if provided.

Array items:

namestringrequired

Tool name (used as identifier)

Example: "search_inventory"

descriptionstringrequired

What the tool does

Example: "Search product inventory"

parametersobjectrequired

Tool parameters in JSON Schema format

propertiesobjectrequired

Parameter definitions keyed by name

Example: {"query":{"type":"string","description":"Search query"},"limit":{"type":"number","description":"Max results"}}

requiredstring[]

Required parameter names

endpointobjectrequired

urlstringrequired

The HTTP endpoint URL to call (must be a public URL, no localhost or private IPs)

Example: "https://api.example.com/search"

method"GET" | "POST" | "PUT" | "PATCH" | "DELETE"required

HTTP method

Example: "POST"

headersobject

Custom headers to include (e.g. Authorization, API keys)

Example: {"Authorization":"Bearer token-abc"}

compact_contextboolean

If true, compact the conversation context before processing the follow-up message. Generates a summary of prior conversation to reduce token usage.

Example: true

compaction_promptstring

Custom prompt for context compaction. Only used when compact_context is true. Overrides the default compaction template.

Example: "Summarize key facts, actions taken, and open items. Keep under 2000 tokens."

Responses

200Follow-up prompt executed successfully

idstringrequired

The run ID that is being resumed

status"running"required

Status of the run after scheduling the follow-up

messagestringrequired

Success message

Errors(4)

400Validation error or run cannot be resumed

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

401Invalid or missing API key

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

404Run not found

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

500Internal server error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

POST/api/v1/agents/run/{id}/stop

Stop a running agent

Stop a running agent and cancel its execution. This will:

Terminate the agent's sandbox immediately
Mark the run as failed with a cancellation message
Return the run's final status

Note: This only affects runs that are currently in "running" status. If the run has already completed or failed, this endpoint will return success with the existing status.

Path Parameters

id

stringrequired

Unique identifier for the agent run

Responses

200Run stopped successfully (or was already stopped/completed)

idstringrequired

The run ID that was stopped

status"failed" | "completed"required

Status of the run after stopping (failed if it was running, or its previous status)

messagestringrequired

Status message

Errors(3)

401Invalid or missing API key

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

404Run not found

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

500Internal server error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

Schedules

Create and manage scheduled agent runs (one-time or recurring)

POST/api/v1/schedules

Create a scheduled agent run

Schedule an agent run to execute once in the future or on a recurring interval.

One-time schedule: Set type: "once" with a run_at timestamp. Recurring schedule: Set type: "recurring" with an interval (minutes, hours, or days).

The agent will use the same prompt for every execution. When a scheduled run fires but the user's concurrent or monthly run limit is reached, the run is skipped and a schedule.run.skipped webhook is sent.

Request Body

type"once" | "recurring"required

Schedule type: 'once' for a single future run, 'recurring' for repeated runs

Example: "recurring"

cronstring

Cron expression for recurring schedules (standard 5-field syntax). Minimum interval is 15 minutes.

Example: "0 */6 * * *"

run_atstring

ISO 8601 timestamp for when to run (required for 'once', optional for 'recurring' as first run time)

Example: "2025-03-01T09:00:00Z"

promptstringrequired

The instruction/task for the AI agent

Example: "Run the test suite and fix any failures"

repostring

GitHub repository in format: owner/repo

Example: "username/repo-name"

branchstring

Git branch to use

Example: "main"

modelstring

AI model to use

Example: "claude-sonnet-4"

providerstring

AI provider

Example: "anthropic"

mode"execute" | "plan"

Run mode

Example: "execute"

webhook_urlstring

URL to receive webhook notifications for schedule events and run completions

auto_create_prboolean

Automatically create a GitHub PR with the agent's changes

toolsToolDefinition[]

External HTTP tools the agent can call during execution

Array items:

namestringrequired

Tool name (used as identifier)

Example: "search_inventory"

descriptionstringrequired

What the tool does

Example: "Search product inventory"

parametersobjectrequired

Tool parameters in JSON Schema format

propertiesobjectrequired

Parameter definitions keyed by name

Example: {"query":{"type":"string","description":"Search query"},"limit":{"type":"number","description":"Max results"}}

requiredstring[]

Required parameter names

endpointobjectrequired

urlstringrequired

The HTTP endpoint URL to call (must be a public URL, no localhost or private IPs)

Example: "https://api.example.com/search"

method"GET" | "POST" | "PUT" | "PATCH" | "DELETE"required

HTTP method

Example: "POST"

headersobject

Custom headers to include (e.g. Authorization, API keys)

Example: {"Authorization":"Bearer token-abc"}

Responses

201Schedule created successfully

idstringrequired

Unique identifier for the schedule

type"once" | "recurring"required

Schedule type

status"active"required

Initial status

next_run_atstringrequired

ISO 8601 timestamp of the next scheduled execution

messagestringrequired

Success message

Errors(3)

400Validation error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

401Invalid or missing API key

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

500Internal server error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

GET/api/v1/schedules

List schedules

Retrieve a list of your scheduled agent runs, optionally filtered by status.

Query Parameters

limit

integer

Maximum number of schedules to return (1-100)

status

"active" | "completed" | "deleted"

Filter by schedule status

Responses

200List of schedules

schedulesScheduleSummary[]required

Array items:

idstringrequired

Schedule ID

type"once" | "recurring"required

Schedule type

status"active" | "completed" | "deleted"required

Schedule status

promptstringrequired

The agent prompt

repostring

Repository in owner/repo format

cronstring

Cron expression (recurring only)

Example: "0 */6 * * *"

next_run_atstring

Next execution time (ISO 8601)

total_runsnumberrequired

Number of successful runs

total_skipsnumberrequired

Number of skipped runs

last_run_atstring

Last execution time (ISO 8601)

created_atstringrequired

Creation time (ISO 8601)

Errors(2)

401Invalid or missing API key

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

500Internal server error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

GET/api/v1/schedules/{id}

Get schedule details

Retrieve the details and status of a specific schedule.

Path Parameters

id

stringrequired

Unique identifier for the schedule

Responses

200Schedule details

Errors(3)

401Invalid or missing API key

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

404Schedule not found

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

500Internal server error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

DELETE/api/v1/schedules/{id}

Delete a schedule

Delete a schedule and cancel future executions.

Note: This does not cancel any agent runs that are already in progress from this schedule. It only prevents future scheduled runs.

Path Parameters

id

stringrequired

Unique identifier for the schedule

Responses

200Schedule deleted successfully

idstringrequired

Schedule ID

status"deleted"required

Status after deletion

messagestringrequired

Success message

Errors(3)

401Invalid or missing API key

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

404Schedule not found

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

500Internal server error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

Providers and Models

GET/api/v1/providers

List supported providers

Get a list of all supported AI providers and their required credentials.

This endpoint is public and does not require authentication.

Use this to determine which API keys you need to configure for each provider.

Responses

200List of supported providers

providersobject[]required

Array items:

idstringrequired

Provider identifier

Example: "anthropic"

namestringrequired

Human-readable provider name

Example: "Anthropic"

credentialsobject[]required

Required credentials for this provider

Array items:

keystringrequired

Environment variable name

Example: "ANTHROPIC_API_KEY"

labelstringrequired

Human-readable label

Example: "API Key"

requiredboolean

Whether this credential is required (default: true)

placeholderstring

Example value format

Example: "sk-ant-..."

GET/api/v1/models

List supported models

Get a list of supported AI models, optionally filtered by provider.

This endpoint is public and does not require authentication.

The response includes the 5 most recent models for each supported provider (or just the specified provider), with details like:

Model ID (use this in API requests)
Human-readable name
Capabilities (reasoning, tool calling)
Context limits and pricing

Data is sourced from models.dev.

Query Parameters

provider

string

Filter by provider (e.g., 'anthropic', 'openai', 'google')

Responses

200List of supported models

generatedAtstringrequired

ISO 8601 timestamp when this data was last generated

Example: "2026-01-28T15:36:36.566Z"

sourcestringrequired

Data source URL

Example: "https://models.dev"

modelsobjectrequired

Models grouped by provider ID

Models

Schema definitions for request and response objects.

CreateAgentRunResponse

idstringrequired

Unique identifier for the agent run

titlestring

Auto-generated run title

status"queued"required

Initial status of a new run

messagestringrequired

Success message

Error

errorstringrequired

Error type

Example: "Validation Error"

messagestringrequired

Detailed error message

Example: "repo: repo must be in format: owner/repo"

CreateAgentRunRequest

repostring

GitHub repository in format: owner/repo. If not specified, uses your default repository.

Example: "username/repo-name"

promptstringrequired

The instruction/task for the AI agent to execute

Example: "Add a new endpoint to handle user authentication"

system_promptstring

Optional replacement for the OpenCode system prompt. If provided, this prompt is sent as the full system prompt for the run instead of Codecloud's default.

Example: "You are a concise repository assistant. Follow the user prompt exactly."

modelstring

AI model to use. If not specified, uses your default model. Claude Code requires an Anthropic or Bedrock model; Codex requires an OpenAI model.

Example: "claude-opus-4.5"

providerstring

AI provider. If not specified, uses your default provider. Claude Code supports anthropic and amazon-bedrock; Codex supports openai.

Example: "anthropic"

branchstring

Git branch to use (defaults to repo's default branch)

Example: "main"

webhook_urlstring

URL to receive webhook notifications when the run completes

Example: "https://example.com/webhooks/agent-complete"

mode"execute" | "plan"default: "execute"

Run mode: 'execute' runs the agent normally, 'plan' returns a plan without making changes

Example: "execute"

auto_create_prbooleandefault: true

If true, automatically create a GitHub PR with the agent's changes after completion

Example: true

blank_workspacebooleandefault: false

agent_provider"opencode" | "claude-code" | "codex"

Agent runtime: 'claude-code' (Anthropic CLI), 'codex' (OpenAI CLI), or 'opencode' (default). If omitted, uses your default runtime.

Example: "claude-code"

agent_auth_method"subscription" | "api-key"

For Claude Code or Codex: 'subscription' uses a connected Claude or ChatGPT subscription; 'api-key' uses a provider key. If omitted, uses the method saved on your account.

Example: "subscription"

toolsToolDefinition[]

External HTTP tools the agent can call during execution. Supported on OpenCode only. Each tool defines its own endpoint and auth headers.

Array items:

namestringrequired

Tool name (used as identifier)

Example: "search_inventory"

descriptionstringrequired

What the tool does

Example: "Search product inventory"

parametersobjectrequired

Tool parameters in JSON Schema format

propertiesobjectrequired

Parameter definitions keyed by name

Example: {"query":{"type":"string","description":"Search query"},"limit":{"type":"number","description":"Max results"}}

requiredstring[]

Required parameter names

endpointobjectrequired

urlstringrequired

The HTTP endpoint URL to call (must be a public URL, no localhost or private IPs)

Example: "https://api.example.com/search"

method"GET" | "POST" | "PUT" | "PATCH" | "DELETE"required

HTTP method

Example: "POST"

headersobject

Custom headers to include (e.g. Authorization, API keys)

Example: {"Authorization":"Bearer token-abc"}

agentsobject[]

Subagent definitions available to the parent agent during execution. Each subagent has a focused prompt and tool subset.

Array items:

namestringrequired

descriptionstringrequired

mode"subagent"required

promptstringrequired

toolsobjectrequired

max_turnsinteger

ToolDefinition

namestringrequired

Tool name (used as identifier)

Example: "search_inventory"

descriptionstringrequired

What the tool does

Example: "Search product inventory"

parametersobjectrequired

Tool parameters in JSON Schema format

propertiesobjectrequired

Parameter definitions keyed by name

Example: {"query":{"type":"string","description":"Search query"},"limit":{"type":"number","description":"Max results"}}

requiredstring[]

Required parameter names

endpointobjectrequired

urlstringrequired

The HTTP endpoint URL to call (must be a public URL, no localhost or private IPs)

Example: "https://api.example.com/search"

method"GET" | "POST" | "PUT" | "PATCH" | "DELETE"required

HTTP method

Example: "POST"

headersobject

Custom headers to include (e.g. Authorization, API keys)

Example: {"Authorization":"Bearer token-abc"}

ListAgentRunsResponse

runsRunSummary[]required

Array items:

idstringrequired

Unique identifier for the agent run

titlestring

Auto-generated run title

status"queued" | "running" | "completed" | "failed"required

Current status of the agent run

modelstring

Model used for this run

Example: "claude-sonnet-4-5"

providerstring

Provider used for this run

Example: "anthropic"

repostring

GitHub repository in format: owner/repo, or absent for blank_workspace runs

createdAtstringrequired

ISO 8601 timestamp when the run was created

Example: "2025-01-16T12:00:00.000Z"

completedAtstring

ISO 8601 timestamp when the run completed

RunSummary

idstringrequired

Unique identifier for the agent run

titlestring

Auto-generated run title

status"queued" | "running" | "completed" | "failed"required

Current status of the agent run

modelstring

Model used for this run

Example: "claude-sonnet-4-5"

providerstring

Provider used for this run

Example: "anthropic"

repostring

GitHub repository in format: owner/repo, or absent for blank_workspace runs

createdAtstringrequired

ISO 8601 timestamp when the run was created

Example: "2025-01-16T12:00:00.000Z"

completedAtstring

ISO 8601 timestamp when the run completed

RunDetail

idstringrequired

Unique identifier for the agent run

titlestring

Auto-generated run title

status"queued" | "running" | "completed" | "failed"required

Current status of the agent run

mode"execute" | "plan"

Run mode ('execute' or 'plan')

modelstring

Model used for this run

Example: "claude-sonnet-4-5"

providerstring

Provider used for this run

Example: "anthropic"

resultstring

The agent's output (only present when status is 'completed')

planstring

The agent's plan (only present when mode is 'plan' and status is 'completed')

errorstring

Error message (only present when status is 'failed')

repostring

GitHub repository in format: owner/repo, or absent for blank_workspace runs

promptstringrequired

The instruction/task for the AI agent

pr_urlstring

URL of the created PR (only present if auto_create_pr was true and PR was created)

Example: "https://github.com/owner/repo/pull/123"

pr_numbernumber

Number of the created PR (only present if auto_create_pr was true and PR was created)

Example: 123

prsobject[]required

All pull requests created by this run (supports multiple PRs per run)

Array items:

urlstringrequired

Full URL of the PR

numbernumberrequired

PR number

branchstringrequired

Branch name used for the PR

repostringrequired

Repository in format: owner/repo

titlestring

PR title

input_tokensnumber

Input tokens used

output_tokensnumber

Output tokens used (estimated while running)

schedule_idstring

ID of the schedule that created this run (if applicable)

createdAtstringrequired

ISO 8601 timestamp when the run was created

Example: "2025-01-16T12:00:00.000Z"

startedAtstring

ISO 8601 timestamp when the run started executing

completedAtstring

ISO 8601 timestamp when the run completed

ResumeAgentRunResponse

idstringrequired

The run ID that is being resumed

status"running"required

Status of the run after scheduling the follow-up

messagestringrequired

Success message

ResumeAgentRunRequest

promptstringrequired

The follow-up instruction/task for the AI agent to execute in the existing session

Example: "Now add unit tests for the authentication endpoint"

system_promptstring

Optional replacement for the OpenCode system prompt on this run and future follow-ups.

Example: "Continue as a concise repository assistant. Follow the user prompt exactly."

mode"execute" | "plan"

Run mode for this follow-up: 'execute' runs the agent normally, 'plan' returns a plan without making changes. Defaults to the original run's mode.

Example: "execute"

update_prboolean

If true, push changes to the existing PR branch (or create a new PR if none exists). Only valid for execute mode.

Example: true

idempotency_keystring

Optional unique key to ensure exactly-once processing. If a request with this key was already processed, the same response is returned. Keys expire after 24 hours.

Example: "msg-12345-abc"

toolsToolDefinition[]

External HTTP tools the agent can call during execution. Overrides tools from the original run if provided.

Array items:

namestringrequired

Tool name (used as identifier)

Example: "search_inventory"

descriptionstringrequired

What the tool does

Example: "Search product inventory"

parametersobjectrequired

Tool parameters in JSON Schema format

propertiesobjectrequired

Parameter definitions keyed by name

Example: {"query":{"type":"string","description":"Search query"},"limit":{"type":"number","description":"Max results"}}

requiredstring[]

Required parameter names

endpointobjectrequired

urlstringrequired

The HTTP endpoint URL to call (must be a public URL, no localhost or private IPs)

Example: "https://api.example.com/search"

method"GET" | "POST" | "PUT" | "PATCH" | "DELETE"required

HTTP method

Example: "POST"

headersobject

Custom headers to include (e.g. Authorization, API keys)

Example: {"Authorization":"Bearer token-abc"}

compact_contextboolean

If true, compact the conversation context before processing the follow-up message. Generates a summary of prior conversation to reduce token usage.

Example: true

compaction_promptstring

Custom prompt for context compaction. Only used when compact_context is true. Overrides the default compaction template.

Example: "Summarize key facts, actions taken, and open items. Keep under 2000 tokens."

StopAgentRunResponse

idstringrequired

The run ID that was stopped

status"failed" | "completed"required

Status of the run after stopping (failed if it was running, or its previous status)

messagestringrequired

Status message

CreateScheduleResponse

idstringrequired

Unique identifier for the schedule

type"once" | "recurring"required

Schedule type

status"active"required

Initial status

next_run_atstringrequired

ISO 8601 timestamp of the next scheduled execution

messagestringrequired

Success message

CreateScheduleRequest

type"once" | "recurring"required

Schedule type: 'once' for a single future run, 'recurring' for repeated runs

Example: "recurring"

cronstring

Cron expression for recurring schedules (standard 5-field syntax). Minimum interval is 15 minutes.

Example: "0 */6 * * *"

run_atstring

ISO 8601 timestamp for when to run (required for 'once', optional for 'recurring' as first run time)

Example: "2025-03-01T09:00:00Z"

promptstringrequired

The instruction/task for the AI agent

Example: "Run the test suite and fix any failures"

repostring

GitHub repository in format: owner/repo

Example: "username/repo-name"

branchstring

Git branch to use

Example: "main"

modelstring

AI model to use

Example: "claude-sonnet-4"

providerstring

AI provider

Example: "anthropic"

mode"execute" | "plan"default: "execute"

Run mode

Example: "execute"

webhook_urlstring

URL to receive webhook notifications for schedule events and run completions

auto_create_prbooleandefault: true

Automatically create a GitHub PR with the agent's changes

toolsToolDefinition[]

External HTTP tools the agent can call during execution

Array items:

namestringrequired

Tool name (used as identifier)

Example: "search_inventory"

descriptionstringrequired

What the tool does

Example: "Search product inventory"

parametersobjectrequired

Tool parameters in JSON Schema format

propertiesobjectrequired

Parameter definitions keyed by name

Example: {"query":{"type":"string","description":"Search query"},"limit":{"type":"number","description":"Max results"}}

requiredstring[]

Required parameter names

endpointobjectrequired

urlstringrequired

The HTTP endpoint URL to call (must be a public URL, no localhost or private IPs)

Example: "https://api.example.com/search"

method"GET" | "POST" | "PUT" | "PATCH" | "DELETE"required

HTTP method

Example: "POST"

headersobject

Custom headers to include (e.g. Authorization, API keys)

Example: {"Authorization":"Bearer token-abc"}

ListSchedulesResponse

schedulesScheduleSummary[]required

Array items:

idstringrequired

Schedule ID

type"once" | "recurring"required

Schedule type

status"active" | "completed" | "deleted"required

Schedule status

promptstringrequired

The agent prompt

repostring

Repository in owner/repo format

cronstring

Cron expression (recurring only)

Example: "0 */6 * * *"

next_run_atstring

Next execution time (ISO 8601)

total_runsnumberrequired

Number of successful runs

total_skipsnumberrequired

Number of skipped runs

last_run_atstring

Last execution time (ISO 8601)

created_atstringrequired

Creation time (ISO 8601)

ScheduleSummary

idstringrequired

Schedule ID

type"once" | "recurring"required

Schedule type

status"active" | "completed" | "deleted"required

Schedule status

promptstringrequired

The agent prompt

repostring

Repository in owner/repo format

cronstring

Cron expression (recurring only)

Example: "0 */6 * * *"

next_run_atstring

Next execution time (ISO 8601)

total_runsnumberrequired

Number of successful runs

total_skipsnumberrequired

Number of skipped runs

last_run_atstring

Last execution time (ISO 8601)

created_atstringrequired

Creation time (ISO 8601)

ScheduleDetail

Type: any

DeleteScheduleResponse

idstringrequired

Schedule ID

status"deleted"required

Status after deletion

messagestringrequired

Success message

ModelsResponse

generatedAtstringrequired

ISO 8601 timestamp when this data was last generated

Example: "2026-01-28T15:36:36.566Z"

sourcestringrequired

Data source URL

Example: "https://models.dev"

modelsobjectrequired

Models grouped by provider ID

Model

idstringrequired

Model identifier to use in API requests

namestringrequired

Human-readable model name

releaseDatestring

Release date (YYYY-MM-DD)

reasoningbooleanrequired

Whether the model supports reasoning/thinking

toolCallbooleanrequired

Whether the model supports tool calling

contextLimitnumber

Maximum context window in tokens

inputCostnumber

Cost per million input tokens (USD)

outputCostnumber

Cost per million output tokens (USD)