---
title: "Read one agent document"
description: "Read one agent document — Spinrun Build REST API operation."
url: https://docs.spinrun.ai/api/agents/get-agent
markdown_url: https://docs.spinrun.ai/api/agents/get-agent.md
---

# Read one agent document

Read one agent document — Spinrun Build REST API operation.

## GET /api/build/agents/{ref}

Read one agent document

Operation id: `getAgent`

### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| ref | path | yes | string | Agent or workflow id or slug. |

### Responses

| Status | Description |
|---|---|
| 200 | The document. `ETag` carries its `updated_at`. |
| 401 | No or invalid token. The `WWW-Authenticate` header names the authorization server. |
| 403 | The grant has no Build authorization. |
| 404 | No such agent, workflow or run visible to this token. |

#### 200 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "const": "spinrun.agent/v1",
          "description": "Document discriminator."
        },
        "id": {
          "description": "Server id. Omit when creating.",
          "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)$"
        },
        "slug": {
          "description": "URL slug. Cannot change after creation.",
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "status": {
          "description": "Read-only lifecycle status.",
          "type": "string",
          "enum": [
            "draft",
            "active",
            "archived"
          ]
        },
        "updated_at": {
          "description": "Version stamp. Required on replace; travels as If-Match too.",
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80,
          "description": "Display name."
        },
        "description": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 500
            },
            {
              "type": "null"
            }
          ],
          "description": "What the agent does."
        },
        "icon": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 40
            },
            {
              "type": "null"
            }
          ],
          "description": "Icon preset."
        },
        "space": {
          "type": "object",
          "properties": {
            "team": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160,
                  "description": "A human name for the thing: slug, address or id."
                },
                {
                  "type": "null"
                }
              ],
              "description": "Team slug, or null for the workspace space."
            }
          },
          "required": [
            "team"
          ],
          "additionalProperties": false,
          "description": "Where the agent lives."
        },
        "folder": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 1000
            },
            {
              "type": "null"
            }
          ],
          "description": "Folder path within the space."
        },
        "instructions": {
          "type": "string",
          "maxLength": 8192,
          "description": "The system instructions."
        },
        "model": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Model id, e.g. spinrun default or a named model."
        },
        "max_steps": {
          "type": "integer",
          "minimum": 1,
          "maximum": 40,
          "description": "Maximum tool steps per run."
        },
        "reasoning_effort": {
          "description": "Absent = the model default.",
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "tools": {
          "type": "object",
          "properties": {
            "apps": {
              "maxItems": 50,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "description": "A human name for the thing: slug, address or id."
              },
              "description": "App slugs the agent may use."
            },
            "connections": {
              "anyOf": [
                {
                  "type": "string",
                  "const": "all"
                },
                {
                  "minItems": 1,
                  "maxItems": 200,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160,
                    "description": "A human name for the thing: slug, address or id."
                  }
                }
              ],
              "description": "\"all\" or explicit connection addresses."
            },
            "disabled_tools": {
              "maxItems": 200,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "description": "A human name for the thing: slug, address or id."
              },
              "description": "Tool slugs to hide."
            },
            "approval": {
              "type": "string",
              "enum": [
                "destructive",
                "write"
              ],
              "description": "Which tool calls need human approval."
            }
          },
          "required": [
            "apps",
            "connections",
            "disabled_tools",
            "approval"
          ],
          "additionalProperties": false,
          "description": "What the agent may touch."
        },
// … 363 more lines elided
```

#### 401 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 403 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 404 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```