### API Overview: codecloud API

Source: https://codecloud.dev/api/openapi.json

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

## 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](/app).

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

```json
{
  "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:

```javascript
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](/app), `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`.

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

| Field | Type | Description |
|-------|------|-------------|
| `event` | string | Always `agent.progress` |
| `run_id` | string | The agent run ID |
| `status` | string | Always `running` |
| `thinking` | string | Current agent output (truncated) |

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

```json
{
  "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):

```json
{
  "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:**

```json
{
  "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:**

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

```yaml
# codecloud API
# Version: 1.0.0

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

## 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](/app).

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

```json
{
  "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:

```javascript
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](/app), `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`.

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

| Field | Type | Description |
|-------|------|-------------|
| `event` | string | Always `agent.progress` |
| `run_id` | string | The agent run ID |
| `status` | string | Always `running` |
| `thinking` | string | Current agent output (truncated) |

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

```json
{
  "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):

```json
{
  "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:**

```json
{
  "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:**

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

# Base URL: https://codecloud.dev
```

--------------------------------

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

Source: https://codecloud.dev/api/openapi.json

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.

```markdown
### Parameters

- **id** (string, path, required): Unique identifier for the agent run (example: "jd7x8k9m2n3p4q5r")

### Request Body

**Content-Type:** application/json

- **prompt** (string) (required): 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** (string (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") ("execute"|"plan")
- **update_pr** (boolean): 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_key** (string): 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")
- **tools** (array (ToolDefinition)): External HTTP tools the agent can call during execution. Overrides tools from the original run if provided.
  Array items:
    - **name** (string) (required): Tool name (used as identifier) (example: "search_inventory")
    - **description** (string) (required): What the tool does (example: "Search product inventory")
    - **parameters** (object) (required): Tool parameters in JSON Schema format
      - **properties** (object) (required): Parameter definitions keyed by name (example: {"query":{"type":"string","description":"Search query"},"limit":{"type":"number","description":"Max results"}})
      - **required** (array (string)): Required parameter names
    - **endpoint** (object) (required)
      - **url** (string (uri)) (required): The HTTP endpoint URL to call (example: "https://api.example.com/search")
      - **method** (string (GET|POST|PUT|PATCH|DELETE)) (required): HTTP method (example: "POST") ("GET"|"POST"|"PUT"|"PATCH"|"DELETE")
      - **headers** (object): Custom headers to include (e.g. Authorization, API keys) (example: {"Authorization":"Bearer token-abc"})

### Responses

#### 200 - Follow-up prompt executed successfully

**ResumeAgentRunResponse**
- **id** (string) (required): The run ID that is being resumed
- **status** (string (running)) (required): Status of the run after scheduling the follow-up ("running")
- **message** (string) (required): Success message

#### 400 - Validation error or run cannot be resumed

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 401 - Invalid or missing API key

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 404 - Run not found

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 500 - Internal server error

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

### Example Usage

```bash
curl -X POST "https://codecloud.dev/api/v1/agents/run/{id}/message" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Now add unit tests for the authentication endpoint",
  "mode": "execute",
  "update_pr": true,
  "idempotency_key": "msg-12345-abc",
  "tools": [
    "value"
  ]
}'
```

```

--------------------------------

### GET /api/v1/models

Source: https://codecloud.dev/api/openapi.json

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](https://models.dev).

```markdown
### Parameters

- **provider** (string, query, optional): Filter by provider (e.g., 'anthropic', 'openai', 'google') (example: "anthropic")

### Responses

#### 200 - List of supported models

**ModelsResponse**
- **generatedAt** (string) (required): ISO 8601 timestamp when this data was last generated (example: "2026-01-28T15:36:36.566Z")
- **source** (string) (required): Data source URL (example: "https://models.dev")
- **models** (object) (required): Models grouped by provider ID

### Example Usage

```bash
curl -X GET "https://codecloud.dev/api/v1/models?provider=anthropic"
```

```

--------------------------------

### GET /api/v1/schedules/{id}

Source: https://codecloud.dev/api/openapi.json

Retrieve the details and status of a specific schedule.

```markdown
### Parameters

- **id** (string, path, required): Unique identifier for the schedule

### Responses

#### 200 - Schedule details

**ScheduleDetail**
- **id** (string) (required): Schedule ID
- **type** (string (once|recurring)) (required): Schedule type ("once"|"recurring")
- **status** (string (active|completed|deleted)) (required): Schedule status ("active"|"completed"|"deleted")
- **prompt** (string) (required): The agent prompt
- **repo** (string): Repository in owner/repo format
- **cron** (string): Cron expression (recurring only) (example: "0 */6 * * *")
- **next_run_at** (string): Next execution time (ISO 8601)
- **total_runs** (number) (required): Number of successful runs
- **total_skips** (number) (required): Number of skipped runs
- **last_run_at** (string): Last execution time (ISO 8601)
- **created_at** (string) (required): Creation time (ISO 8601)
- **last_run_id** (string): ID of the last agent run

#### 401 - Invalid or missing API key

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 404 - Schedule not found

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 500 - Internal server error

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

### Example Usage

```bash
curl -X GET "https://codecloud.dev/api/v1/schedules/{id}"
```

```

--------------------------------

### GET /api/v1/providers

Source: https://codecloud.dev/api/openapi.json

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.

```markdown
### Responses

#### 200 - List of supported providers

- **providers** (array (object)) (required)
  Array items:
    - **id** (string) (required): Provider identifier (example: "anthropic")
    - **name** (string) (required): Human-readable provider name (example: "Anthropic")
    - **credentials** (array (object)) (required): Required credentials for this provider
      Array items:
        - **key** (string) (required): Environment variable name (example: "ANTHROPIC_API_KEY")
        - **label** (string) (required): Human-readable label (example: "API Key")
        - **required** (boolean): Whether this credential is required (default: true)
        - **placeholder** (string): Example value format (example: "sk-ant-...")

### Example Usage

```bash
curl -X GET "https://codecloud.dev/api/v1/providers"
```

```

--------------------------------

### GET /api/v1/agents

Source: https://codecloud.dev/api/openapi.json

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

```markdown
### Parameters

- **limit** (integer, query, optional): Maximum number of runs to return (1-100) (example: 10)
- **status** (string (queued|running|completed|failed), query, optional): Filter by run status (example: "completed")

### Responses

#### 200 - List of agent runs

**ListAgentRunsResponse**
- **runs** (array (RunSummary)) (required)
  Array items:
    - **id** (string) (required): Unique identifier for the agent run
    - **title** (string): Auto-generated run title
    - **status** (string (queued|running|completed|failed)) (required): Current status of the agent run ("queued"|"running"|"completed"|"failed")
    - **model** (string): Model used for this run (example: "claude-sonnet-4-5")
    - **provider** (string): Provider used for this run (example: "anthropic")
    - **repo** (string): GitHub repository in format: owner/repo, or absent for blank_workspace runs
    - **createdAt** (string) (required): ISO 8601 timestamp when the run was created (example: "2025-01-16T12:00:00.000Z")
    - **completedAt** (string): ISO 8601 timestamp when the run completed

#### 400 - Validation error

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 401 - Invalid or missing API key

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 500 - Internal server error

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

### Example Usage

```bash
curl -X GET "https://codecloud.dev/api/v1/agents?limit=10&status=completed"
```

```

--------------------------------

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

Source: https://codecloud.dev/api/openapi.json

Retrieve the details and status of a specific agent run.

```markdown
### Parameters

- **id** (string, path, required): Unique identifier for the agent run (example: "jd7x8k9m2n3p4q5r")

### Responses

#### 200 - Agent run details

**RunDetail**
- **id** (string) (required): Unique identifier for the agent run
- **title** (string): Auto-generated run title
- **status** (string (queued|running|completed|failed)) (required): Current status of the agent run ("queued"|"running"|"completed"|"failed")
- **mode** (string (execute|plan)): Run mode ('execute' or 'plan') ("execute"|"plan")
- **model** (string): Model used for this run (example: "claude-sonnet-4-5")
- **provider** (string): Provider used for this run (example: "anthropic")
- **result** (string): The agent's output (only present when status is 'completed')
- **plan** (string): The agent's plan (only present when mode is 'plan' and status is 'completed')
- **error** (string): Error message (only present when status is 'failed')
- **repo** (string): GitHub repository in format: owner/repo, or absent for blank_workspace runs
- **prompt** (string) (required): The instruction/task for the AI agent
- **pr_url** (string): 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_number** (number): Number of the created PR (only present if auto_create_pr was true and PR was created) (example: 123)
- **prs** (array (object)) (required): All pull requests created by this run (supports multiple PRs per run)
  Array items:
    - **url** (string) (required): Full URL of the PR
    - **number** (number) (required): PR number
    - **branch** (string) (required): Branch name used for the PR
    - **repo** (string) (required): Repository in format: owner/repo
    - **title** (string): PR title
- **input_tokens** (number): Input tokens used
- **output_tokens** (number): Output tokens used (estimated while running)
- **schedule_id** (string): ID of the schedule that created this run (if applicable)
- **createdAt** (string) (required): ISO 8601 timestamp when the run was created (example: "2025-01-16T12:00:00.000Z")
- **startedAt** (string): ISO 8601 timestamp when the run started executing
- **completedAt** (string): ISO 8601 timestamp when the run completed

#### 400 - Invalid run ID format

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 401 - Invalid or missing API key

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 404 - Run not found

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 500 - Internal server error

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

### Example Usage

```bash
curl -X GET "https://codecloud.dev/api/v1/agents/run/{id}"
```

```

--------------------------------

### GET /api/v1/schedules

Source: https://codecloud.dev/api/openapi.json

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

```markdown
### Parameters

- **limit** (integer, query, optional): Maximum number of schedules to return (1-100)
- **status** (string (active|completed|deleted), query, optional): Filter by schedule status

### Responses

#### 200 - List of schedules

**ListSchedulesResponse**
- **schedules** (array (ScheduleSummary)) (required)
  Array items:
    - **id** (string) (required): Schedule ID
    - **type** (string (once|recurring)) (required): Schedule type ("once"|"recurring")
    - **status** (string (active|completed|deleted)) (required): Schedule status ("active"|"completed"|"deleted")
    - **prompt** (string) (required): The agent prompt
    - **repo** (string): Repository in owner/repo format
    - **cron** (string): Cron expression (recurring only) (example: "0 */6 * * *")
    - **next_run_at** (string): Next execution time (ISO 8601)
    - **total_runs** (number) (required): Number of successful runs
    - **total_skips** (number) (required): Number of skipped runs
    - **last_run_at** (string): Last execution time (ISO 8601)
    - **created_at** (string) (required): Creation time (ISO 8601)

#### 401 - Invalid or missing API key

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 500 - Internal server error

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

### Example Usage

```bash
curl -X GET "https://codecloud.dev/api/v1/schedules?limit=0&status=active"
```

```

--------------------------------

### Security: bearerAuth

Source: https://codecloud.dev/api/openapi.json

API key authentication. Get your key from the dashboard.

```markdown
## Security: bearerAuth

**Description:** API key authentication. Get your key from the dashboard.

**Type:** http

**Scheme:** bearer


```

--------------------------------

### POST /api/v1/schedules

Source: https://codecloud.dev/api/openapi.json

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.

```markdown
### Request Body

**Content-Type:** application/json

- **type** (string (once|recurring)) (required): Schedule type: 'once' for a single future run, 'recurring' for repeated runs (example: "recurring") ("once"|"recurring")
- **cron** (string): Cron expression for recurring schedules (standard 5-field syntax). Minimum interval is 15 minutes. (example: "0 */6 * * *")
- **run_at** (string (date-time)): ISO 8601 timestamp for when to run (required for 'once', optional for 'recurring' as first run time) (example: "2025-03-01T09:00:00Z")
- **prompt** (string) (required): The instruction/task for the AI agent (example: "Run the test suite and fix any failures")
- **repo** (string): GitHub repository in format: owner/repo (example: "username/repo-name")
- **branch** (string): Git branch to use (example: "main")
- **model** (string): AI model to use (example: "claude-sonnet-4")
- **provider** (string): AI provider (example: "anthropic")
- **mode** (string (execute|plan)): Run mode (example: "execute") ("execute"|"plan")
- **webhook_url** (string (uri)): URL to receive webhook notifications for schedule events and run completions
- **auto_create_pr** (boolean): Automatically create a GitHub PR with the agent's changes
- **tools** (array (ToolDefinition)): External HTTP tools the agent can call during execution
  Array items:
    - **name** (string) (required): Tool name (used as identifier) (example: "search_inventory")
    - **description** (string) (required): What the tool does (example: "Search product inventory")
    - **parameters** (object) (required): Tool parameters in JSON Schema format
      - **properties** (object) (required): Parameter definitions keyed by name (example: {"query":{"type":"string","description":"Search query"},"limit":{"type":"number","description":"Max results"}})
      - **required** (array (string)): Required parameter names
    - **endpoint** (object) (required)
      - **url** (string (uri)) (required): The HTTP endpoint URL to call (example: "https://api.example.com/search")
      - **method** (string (GET|POST|PUT|PATCH|DELETE)) (required): HTTP method (example: "POST") ("GET"|"POST"|"PUT"|"PATCH"|"DELETE")
      - **headers** (object): Custom headers to include (e.g. Authorization, API keys) (example: {"Authorization":"Bearer token-abc"})

### Responses

#### 201 - Schedule created successfully

**CreateScheduleResponse**
- **id** (string) (required): Unique identifier for the schedule
- **type** (string (once|recurring)) (required): Schedule type ("once"|"recurring")
- **status** (string (active)) (required): Initial status ("active")
- **next_run_at** (string) (required): ISO 8601 timestamp of the next scheduled execution
- **message** (string) (required): Success message

#### 400 - Validation error

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 401 - Invalid or missing API key

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

#### 500 - Internal server error

**Error**
- **error** (string) (required): Error type (example: "Validation Error")
- **message** (string) (required): Detailed error message (example: "repo: repo must be in format: owner/repo")

### Example Usage

```bash
curl -X POST "https://codecloud.dev/api/v1/schedules" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "recurring",
  "cron": "0 */6 * * *",
  "run_at": "2025-03-01T09:00:00Z",
  "prompt": "Run the test suite and fix any failures",
  "repo": "username/repo-name",
  "branch": "main",
  "model": "claude-sonnet-4",
  "provider": "anthropic",
  "mode": "execute",
  "webhook_url": "string",
  "auto_create_pr": "true",
  "tools": [
    "value"
  ]
}'
```

```