---
title: "API"
canonical: https://workspace.socra.com/docs/agents/reference/api
---

# API

Use the Agent API to create and manage agents, configure provider connections, and inspect execution. The reference below is generated from the published `@socra/agent-api` contract.

## Authentication

Send an Account-scoped Socra access token in the `Authorization: Bearer ACCESS_TOKEN` header. Replace `ACCESS_TOKEN` with your token. Account owners and admins manage Agent resources; runtime-only operations require the agent's own identity.

API paths use resource IDs. The CLI additionally resolves agent usernames.

## Execution and credentials

Lifecycle operations can complete asynchronously. Inspect the returned state before assuming the computer is ready. Secret responses contain metadata rather than stored values.

Read [Events and execution](/docs/agents/concepts/events-and-execution) before using mailbox outcomes to track work completion.

## API surface

Base URL: `https://agent.socra.cloud`

## Agents

A managed software worker with an Account identity and durable cloud sandbox.

### Resource schema

- `id` custom, required
- `username` string, required
- `daily_input_tokens` integer | null, required
- `daily_output_tokens` integer | null, required
- `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
- `billing_suspended` boolean, optional
- `allowance_suspended` boolean, optional
- `account` custom, required
- `principal` custom | null, required
- `sandbox` custom | null, required
- `runtime` "codex" | "claude", required
- `model` string (default: "gpt-6-sol"), required
- `reasoning_effort` string | null (default: null), required
- `last_error` string | null, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "username": {
      "type": "string"
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "provisioning",
        "sleeping",
        "waking",
        "upgrading",
        "running",
        "suspended",
        "failed"
      ]
    },
    "billing_suspended": {
      "type": "boolean"
    },
    "allowance_suspended": {
      "type": "boolean"
    },
    "account": {},
    "principal": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "sandbox": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "runtime": {
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "model": {
      "default": "gpt-6-sol",
      "type": "string"
    },
    "reasoning_effort": {
      "default": null,
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "username",
    "daily_input_tokens",
    "daily_output_tokens",
    "status",
    "account",
    "principal",
    "sandbox",
    "runtime",
    "model",
    "reasoning_effort",
    "last_error",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Read own runtime settings

`GET /v1/agents/runtime-settings`

#### Response

- `model` string (min length: 1; max length: 128), required
- `reasoning_effort` string | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "reasoning_effort": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 32
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "model",
    "reasoning_effort"
  ],
  "additionalProperties": false
}
```

### Read cached model catalog

`GET /v1/agents/{agent_id}/models`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `data` object[], required
  - `model` string, required
  - `displayName` string, required
  - `defaultReasoningEffort` string, required
  - `supportedReasoningEfforts` object[], required
    - `reasoningEffort` string, required
    - `description` string, required
- `checked_at` string | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "defaultReasoningEffort": {
            "type": "string"
          },
          "supportedReasoningEfforts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "reasoningEffort": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              },
              "required": [
                "reasoningEffort",
                "description"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "model",
          "displayName",
          "defaultReasoningEffort",
          "supportedReasoningEfforts"
        ],
        "additionalProperties": false
      }
    },
    "checked_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "data",
    "checked_at"
  ],
  "additionalProperties": false
}
```

### Refresh available models

`POST /v1/agents/{agent_id}/models/refresh`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `data` object[], required
  - `model` string, required
  - `displayName` string, required
  - `defaultReasoningEffort` string, required
  - `supportedReasoningEfforts` object[], required
    - `reasoningEffort` string, required
    - `description` string, required
- `checked_at` string | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "defaultReasoningEffort": {
            "type": "string"
          },
          "supportedReasoningEfforts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "reasoningEffort": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              },
              "required": [
                "reasoningEffort",
                "description"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "model",
          "displayName",
          "defaultReasoningEffort",
          "supportedReasoningEfforts"
        ],
        "additionalProperties": false
      }
    },
    "checked_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "data",
    "checked_at"
  ],
  "additionalProperties": false
}
```

### Read AI connection

`GET /v1/agents/{agent_id}/connection`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `status` "not_connected" | "connecting" | "connected" | "reconnect_required", required
- `checked_at` string | null, required
- `available` boolean, required
- `login` object | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "not_connected",
        "connecting",
        "connected",
        "reconnect_required"
      ]
    },
    "checked_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "available": {
      "type": "boolean"
    },
    "login": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "verification_url": {
              "type": "string",
              "const": "https://auth.openai.com/codex/device"
            },
            "user_code": {
              "type": "string",
              "maxLength": 64
            },
            "expires_at": {
              "type": "string"
            }
          },
          "required": [
            "verification_url",
            "user_code",
            "expires_at"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status",
    "checked_at",
    "available",
    "login"
  ],
  "additionalProperties": false
}
```

### Connect ChatGPT

`POST /v1/agents/{agent_id}/connection`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `status` "not_connected" | "connecting" | "connected" | "reconnect_required", required
- `checked_at` string | null, required
- `available` boolean, required
- `login` object | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "not_connected",
        "connecting",
        "connected",
        "reconnect_required"
      ]
    },
    "checked_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "available": {
      "type": "boolean"
    },
    "login": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "verification_url": {
              "type": "string",
              "const": "https://auth.openai.com/codex/device"
            },
            "user_code": {
              "type": "string",
              "maxLength": 64
            },
            "expires_at": {
              "type": "string"
            }
          },
          "required": [
            "verification_url",
            "user_code",
            "expires_at"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status",
    "checked_at",
    "available",
    "login"
  ],
  "additionalProperties": false
}
```

### Check AI connection

`POST /v1/agents/{agent_id}/connection/check`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `status` "not_connected" | "connecting" | "connected" | "reconnect_required", required
- `checked_at` string | null, required
- `available` boolean, required
- `login` object | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "not_connected",
        "connecting",
        "connected",
        "reconnect_required"
      ]
    },
    "checked_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "available": {
      "type": "boolean"
    },
    "login": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "verification_url": {
              "type": "string",
              "const": "https://auth.openai.com/codex/device"
            },
            "user_code": {
              "type": "string",
              "maxLength": 64
            },
            "expires_at": {
              "type": "string"
            }
          },
          "required": [
            "verification_url",
            "user_code",
            "expires_at"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status",
    "checked_at",
    "available",
    "login"
  ],
  "additionalProperties": false
}
```

### Sign out of ChatGPT

`POST /v1/agents/{agent_id}/connection/disconnect`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `status` "not_connected" | "connecting" | "connected" | "reconnect_required", required
- `checked_at` string | null, required
- `available` boolean, required
- `login` object | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "not_connected",
        "connecting",
        "connected",
        "reconnect_required"
      ]
    },
    "checked_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "available": {
      "type": "boolean"
    },
    "login": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "verification_url": {
              "type": "string",
              "const": "https://auth.openai.com/codex/device"
            },
            "user_code": {
              "type": "string",
              "maxLength": 64
            },
            "expires_at": {
              "type": "string"
            }
          },
          "required": [
            "verification_url",
            "user_code",
            "expires_at"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status",
    "checked_at",
    "available",
    "login"
  ],
  "additionalProperties": false
}
```

### Cancel ChatGPT sign-in

`POST /v1/agents/{agent_id}/connection/cancel`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `status` "not_connected" | "connecting" | "connected" | "reconnect_required", required
- `checked_at` string | null, required
- `available` boolean, required
- `login` object | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "not_connected",
        "connecting",
        "connected",
        "reconnect_required"
      ]
    },
    "checked_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "available": {
      "type": "boolean"
    },
    "login": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "verification_url": {
              "type": "string",
              "const": "https://auth.openai.com/codex/device"
            },
            "user_code": {
              "type": "string",
              "maxLength": 64
            },
            "expires_at": {
              "type": "string"
            }
          },
          "required": [
            "verification_url",
            "user_code",
            "expires_at"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status",
    "checked_at",
    "available",
    "login"
  ],
  "additionalProperties": false
}
```

### Pause work while retaining the paid seat and home

`POST /v1/agents/{agent_id}/pause`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `username` string, required
- `daily_input_tokens` integer | null, required
- `daily_output_tokens` integer | null, required
- `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
- `billing_suspended` boolean, optional
- `allowance_suspended` boolean, optional
- `account` custom, required
- `principal` custom | null, required
- `sandbox` custom | null, required
- `runtime` "codex" | "claude", required
- `model` string (default: "gpt-6-sol"), required
- `reasoning_effort` string | null (default: null), required
- `last_error` string | null, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "username": {
      "type": "string"
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "provisioning",
        "sleeping",
        "waking",
        "upgrading",
        "running",
        "suspended",
        "failed"
      ]
    },
    "billing_suspended": {
      "type": "boolean"
    },
    "allowance_suspended": {
      "type": "boolean"
    },
    "account": {},
    "principal": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "sandbox": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "runtime": {
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "model": {
      "default": "gpt-6-sol",
      "type": "string"
    },
    "reasoning_effort": {
      "default": null,
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "username",
    "daily_input_tokens",
    "daily_output_tokens",
    "status",
    "account",
    "principal",
    "sandbox",
    "runtime",
    "model",
    "reasoning_effort",
    "last_error",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Resume a manually paused Agent

`POST /v1/agents/{agent_id}/resume`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `username` string, required
- `daily_input_tokens` integer | null, required
- `daily_output_tokens` integer | null, required
- `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
- `billing_suspended` boolean, optional
- `allowance_suspended` boolean, optional
- `account` custom, required
- `principal` custom | null, required
- `sandbox` custom | null, required
- `runtime` "codex" | "claude", required
- `model` string (default: "gpt-6-sol"), required
- `reasoning_effort` string | null (default: null), required
- `last_error` string | null, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "username": {
      "type": "string"
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "provisioning",
        "sleeping",
        "waking",
        "upgrading",
        "running",
        "suspended",
        "failed"
      ]
    },
    "billing_suspended": {
      "type": "boolean"
    },
    "allowance_suspended": {
      "type": "boolean"
    },
    "account": {},
    "principal": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "sandbox": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "runtime": {
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "model": {
      "default": "gpt-6-sol",
      "type": "string"
    },
    "reasoning_effort": {
      "default": null,
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "username",
    "daily_input_tokens",
    "daily_output_tokens",
    "status",
    "account",
    "principal",
    "sandbox",
    "runtime",
    "model",
    "reasoning_effort",
    "last_error",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Resume Agent provisioning without buying another seat

`POST /v1/agents/{agent_id}/provision`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `username` string, required
- `daily_input_tokens` integer | null, required
- `daily_output_tokens` integer | null, required
- `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
- `billing_suspended` boolean, optional
- `allowance_suspended` boolean, optional
- `account` custom, required
- `principal` custom | null, required
- `sandbox` custom | null, required
- `runtime` "codex" | "claude", required
- `model` string (default: "gpt-6-sol"), required
- `reasoning_effort` string | null (default: null), required
- `last_error` string | null, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "username": {
      "type": "string"
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "provisioning",
        "sleeping",
        "waking",
        "upgrading",
        "running",
        "suspended",
        "failed"
      ]
    },
    "billing_suspended": {
      "type": "boolean"
    },
    "allowance_suspended": {
      "type": "boolean"
    },
    "account": {},
    "principal": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "sandbox": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "runtime": {
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "model": {
      "default": "gpt-6-sol",
      "type": "string"
    },
    "reasoning_effort": {
      "default": null,
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "username",
    "daily_input_tokens",
    "daily_output_tokens",
    "status",
    "account",
    "principal",
    "sandbox",
    "runtime",
    "model",
    "reasoning_effort",
    "last_error",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Read individual Agent seat usage

`GET /v1/agents/{agent_id}/usage`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

object | null

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "used_percent": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "resets_at": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "used_percent",
        "resets_at"
      ],
      "additionalProperties": false
    },
    {
      "type": "null"
    }
  ]
}
```

### Get available Agent seats

`GET /v1/agents/capacity`

#### Response

- `billing_enabled` boolean, required
- `capacity` integer | null, required
- `available` integer | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "billing_enabled": {
      "type": "boolean"
    },
    "capacity": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "available": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "billing_enabled",
    "capacity",
    "available"
  ],
  "additionalProperties": false
}
```

### Create agent

`POST /v1/agents`

#### Request body

- `idempotency_key` string (format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$), optional
- `username` string (min length: 1; max length: 64; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$), required
- `runtime` "codex" | "claude" (default: "codex"), optional
- `daily_input_tokens` integer | null, optional
- `daily_output_tokens` integer | null, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "username": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "runtime": {
      "default": "codex",
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "username"
  ]
}
```

#### Response

- `id` custom, required
- `username` string, required
- `daily_input_tokens` integer | null, required
- `daily_output_tokens` integer | null, required
- `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
- `billing_suspended` boolean, optional
- `allowance_suspended` boolean, optional
- `account` custom, required
- `principal` custom | null, required
- `sandbox` custom | null, required
- `runtime` "codex" | "claude", required
- `model` string (default: "gpt-6-sol"), required
- `reasoning_effort` string | null (default: null), required
- `last_error` string | null, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "username": {
      "type": "string"
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "provisioning",
        "sleeping",
        "waking",
        "upgrading",
        "running",
        "suspended",
        "failed"
      ]
    },
    "billing_suspended": {
      "type": "boolean"
    },
    "allowance_suspended": {
      "type": "boolean"
    },
    "account": {},
    "principal": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "sandbox": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "runtime": {
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "model": {
      "default": "gpt-6-sol",
      "type": "string"
    },
    "reasoning_effort": {
      "default": null,
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "username",
    "daily_input_tokens",
    "daily_output_tokens",
    "status",
    "account",
    "principal",
    "sandbox",
    "runtime",
    "model",
    "reasoning_effort",
    "last_error",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Update agent

`PATCH /v1/agents/{agent_id}`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `username` string (min length: 1; max length: 64; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$), optional
- `model` string (min length: 1; max length: 128), optional
- `reasoning_effort` string | null, optional
- `daily_input_tokens` integer | null, optional
- `daily_output_tokens` integer | null, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "model": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "reasoning_effort": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 32
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    }
  }
}
```

#### Response

- `id` custom, required
- `username` string, required
- `daily_input_tokens` integer | null, required
- `daily_output_tokens` integer | null, required
- `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
- `billing_suspended` boolean, optional
- `allowance_suspended` boolean, optional
- `account` custom, required
- `principal` custom | null, required
- `sandbox` custom | null, required
- `runtime` "codex" | "claude", required
- `model` string (default: "gpt-6-sol"), required
- `reasoning_effort` string | null (default: null), required
- `last_error` string | null, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "username": {
      "type": "string"
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "provisioning",
        "sleeping",
        "waking",
        "upgrading",
        "running",
        "suspended",
        "failed"
      ]
    },
    "billing_suspended": {
      "type": "boolean"
    },
    "allowance_suspended": {
      "type": "boolean"
    },
    "account": {},
    "principal": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "sandbox": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "runtime": {
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "model": {
      "default": "gpt-6-sol",
      "type": "string"
    },
    "reasoning_effort": {
      "default": null,
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "username",
    "daily_input_tokens",
    "daily_output_tokens",
    "status",
    "account",
    "principal",
    "sandbox",
    "runtime",
    "model",
    "reasoning_effort",
    "last_error",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### List agents

`GET /v1/agents`

#### Query parameters

- `limit` integer (min: 1; max: 100), optional
- `after` string, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "after": {
      "type": "string"
    }
  }
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `username` string, required
  - `daily_input_tokens` integer | null, required
  - `daily_output_tokens` integer | null, required
  - `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
  - `billing_suspended` boolean, optional
  - `allowance_suspended` boolean, optional
  - `account` custom, required
  - `principal` custom | null, required
  - `sandbox` custom | null, required
  - `runtime` "codex" | "claude", required
  - `model` string (default: "gpt-6-sol"), required
  - `reasoning_effort` string | null (default: null), required
  - `last_error` string | null, required
  - `created_by` custom, required
  - `created_at` custom, required
  - `updated_at` custom, required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "username": {
            "type": "string"
          },
          "daily_input_tokens": {
            "anyOf": [
              {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 2147483647
              },
              {
                "type": "null"
              }
            ]
          },
          "daily_output_tokens": {
            "anyOf": [
              {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 2147483647
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "provisioning",
              "sleeping",
              "waking",
              "upgrading",
              "running",
              "suspended",
              "failed"
            ]
          },
          "billing_suspended": {
            "type": "boolean"
          },
          "allowance_suspended": {
            "type": "boolean"
          },
          "account": {},
          "principal": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          },
          "sandbox": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          },
          "runtime": {
            "type": "string",
            "enum": [
              "codex",
              "claude"
            ]
          },
          "model": {
            "default": "gpt-6-sol",
            "type": "string"
          },
          "reasoning_effort": {
            "default": null,
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "last_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_by": {},
          "created_at": {},
          "updated_at": {}
        },
        "required": [
          "id",
          "username",
          "daily_input_tokens",
          "daily_output_tokens",
          "status",
          "account",
          "principal",
          "sandbox",
          "runtime",
          "model",
          "reasoning_effort",
          "last_error",
          "created_by",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Get agent

`GET /v1/agents/{agent_id}`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `username` string, required
- `daily_input_tokens` integer | null, required
- `daily_output_tokens` integer | null, required
- `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
- `billing_suspended` boolean, optional
- `allowance_suspended` boolean, optional
- `account` custom, required
- `principal` custom | null, required
- `sandbox` custom | null, required
- `runtime` "codex" | "claude", required
- `model` string (default: "gpt-6-sol"), required
- `reasoning_effort` string | null (default: null), required
- `last_error` string | null, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "username": {
      "type": "string"
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "provisioning",
        "sleeping",
        "waking",
        "upgrading",
        "running",
        "suspended",
        "failed"
      ]
    },
    "billing_suspended": {
      "type": "boolean"
    },
    "allowance_suspended": {
      "type": "boolean"
    },
    "account": {},
    "principal": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "sandbox": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "runtime": {
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "model": {
      "default": "gpt-6-sol",
      "type": "string"
    },
    "reasoning_effort": {
      "default": null,
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "username",
    "daily_input_tokens",
    "daily_output_tokens",
    "status",
    "account",
    "principal",
    "sandbox",
    "runtime",
    "model",
    "reasoning_effort",
    "last_error",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Read agent activity

`POST /v1/agents/{agent_id}/activity`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `after` integer (default: 0; min: 0; max: 9007199254740991), optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "after": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  }
}
```

#### Response

- `state` string, required
- `detail` string | null, required
- `queued` number, required
- `active_message` string | null, required
- `cursor` number, required
- `events` object[], required
  - `seq` number, required
  - `at` string, required
  - `type` string, required
  - `text` string, required
  - `message_id` string | null, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "state": {
      "type": "string"
    },
    "detail": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "queued": {
      "type": "number"
    },
    "active_message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "cursor": {
      "type": "number"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "seq": {
            "type": "number"
          },
          "at": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "message_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "seq",
          "at",
          "type",
          "text",
          "message_id"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "state",
    "detail",
    "queued",
    "active_message",
    "cursor",
    "events"
  ],
  "additionalProperties": false
}
```

### Wake agent

`POST /v1/agents/{agent_id}/wake`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `username` string, required
- `daily_input_tokens` integer | null, required
- `daily_output_tokens` integer | null, required
- `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
- `billing_suspended` boolean, optional
- `allowance_suspended` boolean, optional
- `account` custom, required
- `principal` custom | null, required
- `sandbox` custom | null, required
- `runtime` "codex" | "claude", required
- `model` string (default: "gpt-6-sol"), required
- `reasoning_effort` string | null (default: null), required
- `last_error` string | null, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "username": {
      "type": "string"
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "provisioning",
        "sleeping",
        "waking",
        "upgrading",
        "running",
        "suspended",
        "failed"
      ]
    },
    "billing_suspended": {
      "type": "boolean"
    },
    "allowance_suspended": {
      "type": "boolean"
    },
    "account": {},
    "principal": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "sandbox": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "runtime": {
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "model": {
      "default": "gpt-6-sol",
      "type": "string"
    },
    "reasoning_effort": {
      "default": null,
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "username",
    "daily_input_tokens",
    "daily_output_tokens",
    "status",
    "account",
    "principal",
    "sandbox",
    "runtime",
    "model",
    "reasoning_effort",
    "last_error",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Upgrade agent

`POST /v1/agents/{agent_id}/upgrade`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `username` string, required
- `daily_input_tokens` integer | null, required
- `daily_output_tokens` integer | null, required
- `status` "provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed", required
- `billing_suspended` boolean, optional
- `allowance_suspended` boolean, optional
- `account` custom, required
- `principal` custom | null, required
- `sandbox` custom | null, required
- `runtime` "codex" | "claude", required
- `model` string (default: "gpt-6-sol"), required
- `reasoning_effort` string | null (default: null), required
- `last_error` string | null, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "username": {
      "type": "string"
    },
    "daily_input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "daily_output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "provisioning",
        "sleeping",
        "waking",
        "upgrading",
        "running",
        "suspended",
        "failed"
      ]
    },
    "billing_suspended": {
      "type": "boolean"
    },
    "allowance_suspended": {
      "type": "boolean"
    },
    "account": {},
    "principal": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "sandbox": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "runtime": {
      "type": "string",
      "enum": [
        "codex",
        "claude"
      ]
    },
    "model": {
      "default": "gpt-6-sol",
      "type": "string"
    },
    "reasoning_effort": {
      "default": null,
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "last_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "username",
    "daily_input_tokens",
    "daily_output_tokens",
    "status",
    "account",
    "principal",
    "sandbox",
    "runtime",
    "model",
    "reasoning_effort",
    "last_error",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Delete agent

`DELETE /v1/agents/{agent_id}`

#### Path parameters

- `agent_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

No response body.

## Agent secrets

Write-only credentials injected into new Agent sessions.

### Resource schema

- `id` custom, required
- `agent_id` custom, required
- `name` string, required
- `ready` boolean, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "agent_id": {},
    "name": {
      "type": "string"
    },
    "ready": {
      "type": "boolean"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "agent_id",
    "name",
    "ready",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Create Agent secret

`POST /v1/agent-secrets`

#### Request body

- `agent_id` custom, required
- `name` string (pattern: ^[A-Z][A-Z0-9_]{0,127}$), required
- `value` string (min length: 1; max length: 4096), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agent_id": {},
    "name": {
      "type": "string",
      "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
    },
    "value": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    }
  },
  "required": [
    "agent_id",
    "name",
    "value"
  ]
}
```

#### Response

- `id` custom, required
- `agent_id` custom, required
- `name` string, required
- `ready` boolean, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "agent_id": {},
    "name": {
      "type": "string"
    },
    "ready": {
      "type": "boolean"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "agent_id",
    "name",
    "ready",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### List Agent secrets

`GET /v1/agent-secrets`

#### Query parameters

- `agent_id` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agent_id": {}
  },
  "required": [
    "agent_id"
  ]
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `agent_id` custom, required
  - `name` string, required
  - `ready` boolean, required
  - `created_at` custom, required
  - `updated_at` custom, required
- `has_more` false, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "agent_id": {},
          "name": {
            "type": "string"
          },
          "ready": {
            "type": "boolean"
          },
          "created_at": {},
          "updated_at": {}
        },
        "required": [
          "id",
          "agent_id",
          "name",
          "ready",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean",
      "const": false
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Get Agent secret metadata

`GET /v1/agent-secrets/{id}`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `agent_id` custom, required
- `name` string, required
- `ready` boolean, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "agent_id": {},
    "name": {
      "type": "string"
    },
    "ready": {
      "type": "boolean"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "agent_id",
    "name",
    "ready",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Rotate Agent secret

`PATCH /v1/agent-secrets/{id}`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `value` string (min length: 1; max length: 4096), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "value": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    }
  },
  "required": [
    "value"
  ]
}
```

#### Response

- `id` custom, required
- `agent_id` custom, required
- `name` string, required
- `ready` boolean, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "agent_id": {},
    "name": {
      "type": "string"
    },
    "ready": {
      "type": "boolean"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "agent_id",
    "name",
    "ready",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Delete Agent secret

`DELETE /v1/agent-secrets/{id}`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

No response body.

## Agent messages

A durable event delivered to one managed Agent context.

### Resource schema

- `id` custom, required
- `agent_id` custom, required
- `source_event_id` string, required
- `source` string, required
- `type` string, required
- `subject` string, required
- `payload` object, required
- `status` "queued" | "delivered" | "acknowledged", required
- `delivered_at` custom | null, required
- `acknowledged_at` custom | null, required
- `outcome` "succeeded" | "failed" | "canceled" | null, required
- `result` string | null, required
- `error` string | null, required
- `created_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "agent_id": {},
    "source_event_id": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "subject": {
      "type": "string"
    },
    "payload": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "delivered",
        "acknowledged"
      ]
    },
    "delivered_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "acknowledged_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "outcome": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "succeeded",
            "failed",
            "canceled"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "result": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {}
  },
  "required": [
    "id",
    "agent_id",
    "source_event_id",
    "source",
    "type",
    "subject",
    "payload",
    "status",
    "delivered_at",
    "acknowledged_at",
    "outcome",
    "result",
    "error",
    "created_at"
  ],
  "additionalProperties": false
}
```

### List agent messages

`GET /v1/messages`

#### Query parameters

- `agent_id` custom, required
- `status` "queued" | "delivered" | "acknowledged", optional
- `limit` integer (min: 1; max: 100), optional
- `after` string, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agent_id": {},
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "delivered",
        "acknowledged"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "after": {
      "type": "string"
    }
  },
  "required": [
    "agent_id"
  ]
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `agent_id` custom, required
  - `source_event_id` string, required
  - `source` string, required
  - `type` string, required
  - `subject` string, required
  - `payload` object, required
  - `status` "queued" | "delivered" | "acknowledged", required
  - `delivered_at` custom | null, required
  - `acknowledged_at` custom | null, required
  - `outcome` "succeeded" | "failed" | "canceled" | null, required
  - `result` string | null, required
  - `error` string | null, required
  - `created_at` custom, required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "agent_id": {},
          "source_event_id": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "payload": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "delivered",
              "acknowledged"
            ]
          },
          "delivered_at": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          },
          "acknowledged_at": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          },
          "outcome": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "succeeded",
                  "failed",
                  "canceled"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {}
        },
        "required": [
          "id",
          "agent_id",
          "source_event_id",
          "source",
          "type",
          "subject",
          "payload",
          "status",
          "delivered_at",
          "acknowledged_at",
          "outcome",
          "result",
          "error",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Pull next agent message

`POST /v1/messages/pull`

#### Request body

- `in_flight` custom[] (max items: 1000), optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "in_flight": {
      "maxItems": 1000,
      "type": "array",
      "items": {}
    }
  }
}
```

#### Response

object | null

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "id": {},
        "agent_id": {},
        "source_event_id": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "subject": {
          "type": "string"
        },
        "payload": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "delivered",
            "acknowledged"
          ]
        },
        "delivered_at": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ]
        },
        "acknowledged_at": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ]
        },
        "outcome": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "succeeded",
                "failed",
                "canceled"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "result": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {}
      },
      "required": [
        "id",
        "agent_id",
        "source_event_id",
        "source",
        "type",
        "subject",
        "payload",
        "status",
        "delivered_at",
        "acknowledged_at",
        "outcome",
        "result",
        "error",
        "created_at"
      ],
      "additionalProperties": false
    },
    {
      "type": "null"
    }
  ]
}
```

### Acknowledge agent message

`POST /v1/messages/{message_id}/acknowledge`

#### Path parameters

- `message_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `outcome` "succeeded" | "failed" | "canceled" (default: "succeeded"), optional
- `result` string | null, optional
- `error` string | null, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "outcome": {
      "default": "succeeded",
      "type": "string",
      "enum": [
        "succeeded",
        "failed",
        "canceled"
      ]
    },
    "result": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 64000
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 16000
        },
        {
          "type": "null"
        }
      ]
    }
  }
}
```

#### Response

- `id` custom, required
- `agent_id` custom, required
- `source_event_id` string, required
- `source` string, required
- `type` string, required
- `subject` string, required
- `payload` object, required
- `status` "queued" | "delivered" | "acknowledged", required
- `delivered_at` custom | null, required
- `acknowledged_at` custom | null, required
- `outcome` "succeeded" | "failed" | "canceled" | null, required
- `result` string | null, required
- `error` string | null, required
- `created_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "agent_id": {},
    "source_event_id": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "subject": {
      "type": "string"
    },
    "payload": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "delivered",
        "acknowledged"
      ]
    },
    "delivered_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "acknowledged_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "outcome": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "succeeded",
            "failed",
            "canceled"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "result": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {}
  },
  "required": [
    "id",
    "agent_id",
    "source_event_id",
    "source",
    "type",
    "subject",
    "payload",
    "status",
    "delivered_at",
    "acknowledged_at",
    "outcome",
    "result",
    "error",
    "created_at"
  ],
  "additionalProperties": false
}
```

### Cancel agent message

`POST /v1/messages/{message_id}/cancel`

#### Path parameters

- `message_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `agent_id` custom, required
- `source_event_id` string, required
- `source` string, required
- `type` string, required
- `subject` string, required
- `payload` object, required
- `status` "queued" | "delivered" | "acknowledged", required
- `delivered_at` custom | null, required
- `acknowledged_at` custom | null, required
- `outcome` "succeeded" | "failed" | "canceled" | null, required
- `result` string | null, required
- `error` string | null, required
- `created_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "agent_id": {},
    "source_event_id": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "subject": {
      "type": "string"
    },
    "payload": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "delivered",
        "acknowledged"
      ]
    },
    "delivered_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "acknowledged_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "outcome": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "succeeded",
            "failed",
            "canceled"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "result": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {}
  },
  "required": [
    "id",
    "agent_id",
    "source_event_id",
    "source",
    "type",
    "subject",
    "payload",
    "status",
    "delivered_at",
    "acknowledged_at",
    "outcome",
    "result",
    "error",
    "created_at"
  ],
  "additionalProperties": false
}
```

### Retry agent message

`POST /v1/messages/{message_id}/retry`

#### Path parameters

- `message_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `agent_id` custom, required
- `source_event_id` string, required
- `source` string, required
- `type` string, required
- `subject` string, required
- `payload` object, required
- `status` "queued" | "delivered" | "acknowledged", required
- `delivered_at` custom | null, required
- `acknowledged_at` custom | null, required
- `outcome` "succeeded" | "failed" | "canceled" | null, required
- `result` string | null, required
- `error` string | null, required
- `created_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "agent_id": {},
    "source_event_id": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "subject": {
      "type": "string"
    },
    "payload": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "delivered",
        "acknowledged"
      ]
    },
    "delivered_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "acknowledged_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "outcome": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "succeeded",
            "failed",
            "canceled"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "result": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {}
  },
  "required": [
    "id",
    "agent_id",
    "source_event_id",
    "source",
    "type",
    "subject",
    "payload",
    "status",
    "delivered_at",
    "acknowledged_at",
    "outcome",
    "result",
    "error",
    "created_at"
  ],
  "additionalProperties": false
}
```

## Git hub connections

The GitHub App installation trusted by the current Account.

### Resource schema

- `id` custom, required
- `account` custom, required
- `github_account_id` string, required
- `github_account_login` string, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "account": {},
    "github_account_id": {
      "type": "string"
    },
    "github_account_login": {
      "type": "string"
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "account",
    "github_account_id",
    "github_account_login",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Get GitHub connection

`GET /v1/github/connection`

#### Response

- `id` custom, required
- `account` custom, required
- `github_account_id` string, required
- `github_account_login` string, required
- `created_by` custom, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "account": {},
    "github_account_id": {
      "type": "string"
    },
    "github_account_login": {
      "type": "string"
    },
    "created_by": {},
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "account",
    "github_account_id",
    "github_account_login",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Start GitHub connection

`POST /v1/github/connection/start`

#### Response

- `installation_url` string (format: uri), required
- `expires_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "installation_url": {
      "type": "string",
      "format": "uri"
    },
    "expires_at": {}
  },
  "required": [
    "installation_url",
    "expires_at"
  ],
  "additionalProperties": false
}
```

### Disconnect GitHub

`DELETE /v1/github/connection`

#### Response

No response body.

## Repositories

A GitHub repository made available to managed Agents in an Account.

### Resource schema

- `id` custom, required
- `account` custom, required
- `provider` "github", required
- `external_id` string, required
- `full_name` string (pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$), required
- `clone_url` string (format: uri), required
- `default_branch` string, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "account": {},
    "provider": {
      "type": "string",
      "const": "github"
    },
    "external_id": {
      "type": "string"
    },
    "full_name": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"
    },
    "clone_url": {
      "type": "string",
      "format": "uri"
    },
    "default_branch": {
      "type": "string"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "account",
    "provider",
    "external_id",
    "full_name",
    "clone_url",
    "default_branch",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Add repository

`POST /v1/repositories`

#### Request body

- `full_name` string (pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "full_name": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"
    }
  },
  "required": [
    "full_name"
  ]
}
```

#### Response

- `id` custom, required
- `account` custom, required
- `provider` "github", required
- `external_id` string, required
- `full_name` string (pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$), required
- `clone_url` string (format: uri), required
- `default_branch` string, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "account": {},
    "provider": {
      "type": "string",
      "const": "github"
    },
    "external_id": {
      "type": "string"
    },
    "full_name": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"
    },
    "clone_url": {
      "type": "string",
      "format": "uri"
    },
    "default_branch": {
      "type": "string"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "account",
    "provider",
    "external_id",
    "full_name",
    "clone_url",
    "default_branch",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### List repositories

`GET /v1/repositories`

#### Query parameters

- `limit` integer (min: 1; max: 100), optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `account` custom, required
  - `provider` "github", required
  - `external_id` string, required
  - `full_name` string (pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$), required
  - `clone_url` string (format: uri), required
  - `default_branch` string, required
  - `created_at` custom, required
  - `updated_at` custom, required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "account": {},
          "provider": {
            "type": "string",
            "const": "github"
          },
          "external_id": {
            "type": "string"
          },
          "full_name": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"
          },
          "clone_url": {
            "type": "string",
            "format": "uri"
          },
          "default_branch": {
            "type": "string"
          },
          "created_at": {},
          "updated_at": {}
        },
        "required": [
          "id",
          "account",
          "provider",
          "external_id",
          "full_name",
          "clone_url",
          "default_branch",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Remove repository

`DELETE /v1/repositories/{repository_id}`

#### Path parameters

- `repository_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

No response body.

## Repository grants

Permission for a managed Agent to use a repository.

### Resource schema

- `id` custom, required
- `account` custom, required
- `agent` custom, required
- `repository` custom, required
- `permission` "read" | "write", required
- `created_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "account": {},
    "agent": {},
    "repository": {},
    "permission": {
      "type": "string",
      "enum": [
        "read",
        "write"
      ]
    },
    "created_at": {}
  },
  "required": [
    "id",
    "account",
    "agent",
    "repository",
    "permission",
    "created_at"
  ],
  "additionalProperties": false
}
```

### Grant repository access

`POST /v1/repository-grants`

#### Request body

- `agent` custom, required
- `repository` custom, required
- `permission` "read" | "write" (default: "write"), optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agent": {},
    "repository": {},
    "permission": {
      "default": "write",
      "type": "string",
      "enum": [
        "read",
        "write"
      ]
    }
  },
  "required": [
    "agent",
    "repository"
  ]
}
```

#### Response

- `id` custom, required
- `account` custom, required
- `agent` custom, required
- `repository` custom, required
- `permission` "read" | "write", required
- `created_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "account": {},
    "agent": {},
    "repository": {},
    "permission": {
      "type": "string",
      "enum": [
        "read",
        "write"
      ]
    },
    "created_at": {}
  },
  "required": [
    "id",
    "account",
    "agent",
    "repository",
    "permission",
    "created_at"
  ],
  "additionalProperties": false
}
```

### List repository grants

`GET /v1/repository-grants`

#### Query parameters

- `agent` custom, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agent": {}
  }
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `account` custom, required
  - `agent` custom, required
  - `repository` custom, required
  - `permission` "read" | "write", required
  - `created_at` custom, required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "account": {},
          "agent": {},
          "repository": {},
          "permission": {
            "type": "string",
            "enum": [
              "read",
              "write"
            ]
          },
          "created_at": {}
        },
        "required": [
          "id",
          "account",
          "agent",
          "repository",
          "permission",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Revoke repository access

`DELETE /v1/repository-grants/{grant_id}`

#### Path parameters

- `grant_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

No response body.