Introduction

The Guild public API lets external code — partner integrations, scripts, CI pipelines — act on a Guild account programmatically: hold a conversation with an agent, read agents and skills, create workspaces, publish agent versions, and read session activity.

This is a different surface from the one described in API triggers. API triggers use a trigger API key, scoped to a single trigger, to run one agent on demand. The public API described here uses an account API key, scoped to everything the key’s scopes allow across the whole account, to start and hold full conversations with any agent in the account’s workspaces, and to automate broader account and workspace management.

Conversations

A key can hold a full conversation with an agent: start a chat, read the agent’s replies, and send follow-ups. This is the surface a partner backend integrates against most often, so the whole flow is spelled out on its own page — see Conversations. Session events can be polled or streamed over a WebSocket. The WebSocket is part of the public API but does not appear in the sidebar, because OpenAPI cannot describe WebSockets — see Stream the conversation.

Base URL

https://api.guild.ai/v1

You can explore the API before you create a key. Both of these are unauthenticated:

OpenAPI spec — https://api.guild.ai/v1/openapi.yaml, the machine-readable spec to import into an API client or code generator.
API reference — https://api.guild.ai/v1/docs, the spec rendered as a browsable reference.

Authentication

Every request presents the API key one of two ways: as HTTP Basic Authentication, with the key’s ID as the username and its secret as the password, or as a Bearer token that carries the whole <api_key_id>:<api_key_secret> string in the Authorization header.

# HTTP Basic Authentication
curl -u "<api_key_id>:<api_key_secret>" https://api.guild.ai/v1/agents

# Bearer token
curl -H "Authorization: Bearer <api_key_id>:<api_key_secret>" https://api.guild.ai/v1/agents

The secret is shown exactly once, when the key is created. Settings presents it as a single string: the key id, a colon, then the secret (which starts with glda_). That whole string is exactly what curl -u takes, and it is exactly the Bearer token to send, so there is no need to split it.

Create a key

Open account settings

Go to guild.ai, open the account (user or organization) you want the key to act as, and go to Settings.

Create the key

Give it a name and choose its scopes.

Copy the credentials

Copy the <api_key_id>:<api_key_secret> string shown. It won’t be shown again.

With the CLI

guild api-key create --owner <account> --name "CI key" --scopes "agents:write,workspaces:read"   # prints id:secret once
guild api-key list --owner <account>
guild api-key delete <id>

--owner defaults to the current user’s account. --scopes takes comma-separated <group>:<access> pairs.

A key created without --scopes authenticates but reaches nothing; every request it makes is denied. Always pass the scopes the key needs.

Scopes

A key’s access is limited to the scopes you grant it when you create it. A scope is a (group, access) pair:

Group	What it covers
`agents`	Reading and creating agents, configuring an LLM agent (system prompt, mode, tools), publishing versions
`sessions`	Reading session status, events, tasks, and runtimes with `read`; starting a chat and sending follow-ups with `write` — see Conversations
`workspaces`	Reading and creating workspaces, listing a workspace’s sessions and its installed agents (installed agents also require `agents:read`), adding agents to a workspace
`skills`	Reading and creating skills and skill versions
`integrations`	Attaching an existing credential to a workspace agent, or minting a new one, with `write`. Minting takes an `auth_config_id`, shown as ID in the Authentication card of the integration’s Configuration tab

access is read or write; write implies read. A key created with no scopes can authenticate but reaches nothing. Each endpoint in this reference lists the scope it requires.

A scope only grants access to entities the key’s account can already see or own. It never lets a key reach another account’s private data, and it can’t act as a person — for example, an agents:write key can create and publish agents, but only an admin can make one public.

Request conventions

Ids and names are interchangeable. Wherever a request names another entity (a path segment like {workspace_id_or_name}, or an owner_id field), the account or entity name works as well as the UUID. owner_id defaults to the key’s account. On create endpoints where it is optional (creating an agent, for example), omit it and the key’s own account owns the result. There is no need to look up an account UUID. The id you need next is the top-level one. Responses embed related entities: an install response contains the agent, the workspace, and their owners, each with an id of its own. The id of the thing the call created is always the response’s top-level id field; ids inside nested objects identify those other entities.

Response conventions

List endpoints return a paginated envelope:

{
  "items": [ ],
  "pagination": {
    "total_count": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Pass limit (default 20, max 1000) and offset (default 0) as query parameters to page through results. Errors return the relevant 4xx status with a JSON body:

{
  "error": "not_found",
  "message": "Workspace not found"
}

Status	Meaning
`401`	Missing or invalid credentials.
`403`	Authenticated, but the key’s scopes (or the account’s permissions) don’t allow this action.
`404`	The resource doesn’t exist, or exists but the key can’t see it — Guild returns 404 rather than 403 for reads, so a denied read is indistinguishable from an absent one. On a write, a 404 usually means an id in the path or parameters doesn’t match anything the key can see; check each id against the response it came from.
`400`	The request body or parameters are invalid.

Get Started

Workspaces

Agents

Sessions

Skills

Accounts

Introduction

Conversations

Base URL

Authentication

Create a key

With the CLI

Scopes

Request conventions

Response conventions

​Conversations

​Base URL

​Authentication

​Create a key

​With the CLI

​Scopes

​Request conventions

​Response conventions

Conversations

Base URL

Authentication

Create a key

With the CLI

Scopes

Request conventions

Response conventions