v1.0.0OAS 3.1.0

codecloud API

Download OpenAPI Document

The codecloud API allows you to run AI coding agents on your GitHub repositories.

Contact: codecloud support

Authentication

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

You can generate an API key from your dashboard.

Rate Limits

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.

Agent Runs

Create and manage AI agent runs on your repositories

POST/api/v1/agents

Create a new agent run

Queue a new AI agent to execute a task on your GitHub repository.

Request Body

repostring

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

promptstringrequired

The instruction/task for the AI agent to execute

modelstring

AI model to use. If not specified, uses your default model. Model validation is performed by OpenCode.

providerstring

AI provider. If not specified, uses your default provider.

branchstring

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

webhook_urlstring

URL to receive webhook notifications when the run completes

mode"execute" | "plan"

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

auto_create_prboolean

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

Responses

201Agent run created successfully

idstringrequired

Unique identifier for the agent run

status"queued"required

Initial status of a new run

messagestringrequired

Success message

Errors(3)

400Validation error or bad request

errorstringrequired

Error type

messagestringrequired

Detailed error message

401Invalid or missing API key

errorstringrequired

Error type

messagestringrequired

Detailed error message

500Internal server error

errorstringrequired

Error type

messagestringrequired

Detailed error message

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

Errors(3)

400Validation error

errorstringrequired

Error type

messagestringrequired

Detailed error message

401Invalid or missing API key

errorstringrequired

Error type

messagestringrequired

Detailed error message

500Internal server error

errorstringrequired

Error type

messagestringrequired

Detailed error message

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

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

Current status of the agent run

mode"execute" | "plan"

Run mode ('execute' or 'plan')

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')

repostringrequired

GitHub repository in format: owner/repo

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)

pr_numbernumber

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

createdAtstringrequired

ISO 8601 timestamp when the run was created

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

messagestringrequired

Detailed error message

401Invalid or missing API key

errorstringrequired

Error type

messagestringrequired

Detailed error message

404Run not found

errorstringrequired

Error type

messagestringrequired

Detailed error message

500Internal server error

errorstringrequired

Error type

messagestringrequired

Detailed error message

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.

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

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.

update_prboolean

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

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.

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

messagestringrequired

Detailed error message

401Invalid or missing API key

errorstringrequired

Error type

messagestringrequired

Detailed error message

404Run not found

errorstringrequired

Error type

messagestringrequired

Detailed error message

500Internal server error

errorstringrequired

Error type

messagestringrequired

Detailed error message

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

Stop a running agent

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

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

messagestringrequired

Detailed error message

404Run not found

errorstringrequired

Error type

messagestringrequired

Detailed error message

500Internal server error

errorstringrequired

Error type

messagestringrequired

Detailed error message

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

namestringrequired

Human-readable provider name

credentialsobject[]required

Required credentials for this provider

Array items:

keystringrequired

Environment variable name

labelstringrequired

Human-readable label

requiredboolean

Whether this credential is required (default: true)

placeholderstring

Example value format

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

sourcestringrequired

Data source URL

modelsobjectrequired

Models grouped by provider ID

Models

Schema definitions for request and response objects.

CreateAgentRunResponse

idstringrequired

Unique identifier for the agent run

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"

modelstring

AI model to use. If not specified, uses your default model. Model validation is performed by OpenCode.

Example: "claude-opus-4.5"

providerstring

AI provider. If not specified, uses your default provider.

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

ListAgentRunsResponse

runsRunSummary[]required

RunSummary

idstringrequired

Unique identifier for the agent run

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

Current status of the agent run

repostringrequired

GitHub repository in format: owner/repo

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

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

Current status of the agent run

mode"execute" | "plan"

Run mode ('execute' or 'plan')

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')

repostringrequired

GitHub repository in format: owner/repo

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

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"

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"

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

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)