---
title: "Get an agent"
method: GET
path: "/v1/agents/{agent_id}"
tags: ["Agents"]
---

# Get an agent

`GET /v1/agents/{agent_id}`

Retrieve an agent and its schema details.

Agents can have both a live published version and a draft version with newer
unpublished changes. Use the `version` parameter to choose which state to return.

## Path parameters

- `agent_id` string, uuid, required — The ID of the agent to retrieve.

## Query parameters

- `version` 'published' | 'draft' — Version selector for retrieving a specific agent.

## Response `200`

Successful Response

- AgentDetail — Detailed information for an agent.
  - `id` string, uuid, required — Unique ID for the agent.
  - `organization_id` string, uuid, required — Unique ID of the organization that owns the agent.
  - `name` string, required — Display name of the agent.
  - `status` 'draft' | 'published' | 'unknown', required — Current availability status for an agent.
  - `created_at` string, date-time, required — When the agent was created.
  - `description` string, nullable — Short description of the agent, if provided.
  - `schema` AgentSchema — Schema metadata for an agent.
    - `input` object, required — JSON Schema for the agent's `inputs` object. Use the top-level property keys as input field names when starting a run.
    - `output` object, required — JSON Schema for the `outputs` object returned by `GET /v1/agents/{agent_id}/runs/{run_id}`.
  - `validation` AgentValidation — Result of validating an agent's graph. Mirrors the report computed on every read, so callers can confirm a draft is publishable before calling publish.
    - `valid` boolean, required — Whether the agent's graph is valid and ready to publish.
    - `issues` AgentValidationIssue[] — Problems found while validating the graph. Empty when `valid` is true.
      - `code` string, required — Stable machine-readable identifier for the kind of issue.
      - `message` string, required — Human-readable description of the issue.
      - `node_id` string, nullable — ID of the node the issue applies to, if node-specific.
      - `node_title` string, nullable — Display title of the affected node, if available.
      - `field` string, nullable — Name of the offending field on the node, if field-specific.
      - `field_title` string, nullable — Display title of the affected field, if available.
      - `violation` string, nullable — The specific constraint that was violated, if available.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/cooper-square-technologies/apis/external-api.md) · [All operations](https://skmtc.net/cooper-square-technologies/apis/external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cooper-square-technologies/external-api/revisions/ab03b3c80494/schema)