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

# Read one workflow document

Read one workflow document — Spinrun Build REST API operation.

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

Read one workflow document

Operation id: `getWorkflow`

### 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.workflow/v1",
          "description": "Document discriminator."
        },
        "slug": {
          "type": "string",
          "maxLength": 80,
          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
          "description": "URL slug. Cannot change after creation."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80,
          "description": "Display name."
        },
        "description": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 500
            },
            {
              "type": "null"
            }
          ],
          "description": "What the workflow does."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether the workflow runs."
        },
        "updated_at": {
          "description": "Version stamp. Required on replace.",
          "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))$"
        },
        "space": {
          "type": "object",
          "properties": {
            "team": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                },
                {
                  "type": "null"
                }
              ],
              "description": "Team slug, or null."
            }
          },
          "required": [
            "team"
          ],
          "additionalProperties": false,
          "description": "Where the workflow lives."
        },
        "send_as": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 160
            },
            {
              "type": "null"
            }
          ],
          "description": "Identity runs send as."
        },
        "inputs": {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "maxLength": 40,
            "pattern": "^[a-z0-9_]+$",
            "description": "Input name."
          },
          "additionalProperties": {
            "type": "object",
            "properties": {
              "description": {
                "description": "What the input is for.",
                "type": "string",
                "maxLength": 200
              },
              "default": {
                "description": "Default value."
              }
            },
            "additionalProperties": false,
            "description": "One workflow input."
          },
          "description": "Inputs with optional defaults."
        },
        "schedule": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "cron": {
                  "type": "string",
                  "minLength": 9,
                  "maxLength": 120,
                  "description": "Cron expression."
                },
                "timezone": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 64,
                  "description": "IANA timezone."
                }
              },
              "required": [
                "cron",
                "timezone"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional schedule."
        },
        "steps": {
          "minItems": 1,
          "maxItems": 10,
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "maxLength": 40,
                    "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
                    "description": "Step handle a later step references."
                  },
                  "kind": {
                    "type": "string",
                    "const": "tool",
                    "description": "Step kind."
                  },
                  "tool": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120,
                    "description": "Tool slug to call."
                  },
                  "args": {
                    "default": {},
                    "description": "Arguments for the tool.",
                    "type": "object",
                    "propertyNames": {
                      "type": "string"
                    },
                    "additionalProperties": {}
                  },
                  "after": {
                    "default": [],
                    "description": "Steps this one waits for.",
                    "maxItems": 10,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 40,
                      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
                      "description": "Step handle a later step references."
                    }
                  },
                  "note": {
                    "description": "Author note, not executed.",
                    "type": "string",
                    "maxLength": 300
                  }
                },
                "required": [
                  "id",
                  "kind",
                  "tool",
                  "args",
                  "after"
                ],
                "additionalProperties": false,
                "description": "One tool call in a workflow."
              },
              {
// … 101 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
}
```