> ## Documentation Index > Fetch the complete documentation index at: https://docs.guild.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1. > The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml). > Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer :`. See https://docs.guild.ai/api-reference/introduction#authentication. > To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers. > To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt. # Create a session in a workspace > Requires `sessions:write` on a workspace the key's account owns. A key may create `chat` and `agent_test` sessions; `api_trigger` is a `403`. The key is recorded as the session's `initiator` (serialized `type: "api_key"`), and a chat's agent begins executing `initial_prompt` immediately. ## OpenAPI ````yaml /api-reference/openapi.yaml post /workspaces/{workspace_id_or_name}/sessions openapi: 3.0.3 info: title: Guild Public API version: 1.0.0 description: >- The Guild public API, served at https://api.guild.ai/v1. Authenticate with an account API key, sent as HTTP Basic (key id as the username, secret as the password) or as a Bearer token `:`, or with an OAuth 2.0 access token. Each operation lists the credentials it accepts and the scopes it needs; see https://docs.guild.ai/api-reference/introduction#scopes. Versions are path integers and v1 is the only one: a breaking change ships as a new version rather than changing v1. Lists page with `limit` and `offset` and report `pagination.has_more`. A session-events websocket also exists at wss://api.guild.ai/v1/sessions/{session_id}/events/ws with the same credentials on the handshake; OpenAPI cannot describe websockets, so it is not listed in paths. servers: - url: https://api.guild.ai/v1 description: Production security: [] tags: - name: accounts - name: agents - name: integrations - name: other - name: sessions - name: skills - name: triggers - name: workspaces paths: /workspaces/{workspace_id_or_name}/sessions: post: tags: - workspaces summary: Create a session in a workspace description: >- Requires `sessions:write` on a workspace the key's account owns. A key may create `chat` and `agent_test` sessions; `api_trigger` is a `403`. The key is recorded as the session's `initiator` (serialized `type: "api_key"`), and a chat's agent begins executing `initial_prompt` immediately. operationId: create_workspace_session parameters: - name: workspace_id_or_name in: path required: true schema: type: string requestBody: required: false content: application/json: schema: type: object required: - session_type properties: session_type: type: string enum: - chat - agent_test description: >- `chat` holds a conversation with `agent_id`, starting from `initial_prompt`. `agent_test` runs one agent version, given by `agent_version_id`. agent_id: type: string description: 'For `chat`: the agent to converse with, by id or name.' initial_prompt: type: string description: 'For `chat`, required: the first message.' agent_version_id: type: string description: >- For `agent_test`, required: the agent version to run, draft or published. context_override_id: type: string description: >- For `agent_test`: a context version to run with instead of the active one. responses: '201': description: The created session content: application/json: schema: $ref: '#/components/schemas/Session' links: Session: operationId: gen_session parameters: session_id: $response.body#/id description: Read the session; its root task's status shows progress. SessionEvents: operationId: gen_session_events parameters: session_id: $response.body#/id description: Read the session's events as they arrive. '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - apiKey: [] - bearerApiKey: [] - oauth2: - sessions:write components: schemas: Session: oneOf: - $ref: '#/components/schemas/SessionAgentTest' - $ref: '#/components/schemas/SessionChat' - $ref: '#/components/schemas/SessionGateway' - $ref: '#/components/schemas/SessionTriggerApi' - $ref: '#/components/schemas/SessionTriggerTime' - $ref: '#/components/schemas/SessionTriggerWebhook' ErrorResponse: type: object properties: error: type: string message: type: string SessionAgentTest: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time initiator_id: type: string format: uuid description: >- Who started this agent test session: a user, or an account API key testing from CI. test_type: type: string enum: - MANUAL - EVAL description: >- Eval trials run as agent-test sessions; this separates them from sessions a person started from the agent editor. version_override_id: type: string format: uuid description: The specific agent version being tested in this session. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. context_override_id: type: string format: uuid nullable: true description: Optional context override for testing purposes. interrupted_at: type: string format: date-time nullable: true description: >- Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. seed_context: type: string maxLength: 262144 nullable: true description: >- Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. SessionChat: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time initiator_id: type: string format: uuid description: >- Who started this chat session: a user, or an account API key acting as its account. workspace_id: type: string format: uuid description: The workspace this session belongs to. archived_at: type: string format: date-time nullable: true archived_by_id: type: string format: uuid nullable: true assistant_version_id: type: string format: uuid nullable: true description: >- The assistant version resolved for this chat session. Null for legacy sessions and direct agent sessions that did not use the assistant. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: >- Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. name: type: string maxLength: 100 nullable: true description: >- The name/title of this chat session. Usually generated by an LLM based on the first prompt. origin: type: string enum: - CHAT - INSIGHTS nullable: true description: >- Set only on chats in a Smith workspace: CHAT for the Smith chat, INSIGHTS for a conversation the Ask Insights panel started. Chat lists filter on it to keep panel conversations out of the sidebar. seed_context: type: string maxLength: 262144 nullable: true description: >- Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. SessionGateway: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time initiator_id: type: string format: uuid description: >- The member whose calls this session carries. A profile an admin declares is used by everyone in the workspace, so sessions are per member rather than per profile. ip_address: type: string maxLength: 45 description: The IP address of the client which initiated this session. last_active_at: type: string format: date-time description: >- When this session last carried a tool call. Written on every call: a session rolls over once it goes quiet, and nothing else touches the row, so updated_at would measure the session's age instead of its idleness. profile_id: type: string format: uuid description: >- The gateway profile this session's calls run as. Names the install directly, rather than leaving it to be inferred from the agent version, which several profiles share. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: >- Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. seed_context: type: string maxLength: 262144 nullable: true description: >- Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. user_agent: type: string maxLength: 1024 nullable: true description: >- The User-Agent of the connecting client, naming the assistant driving this profile. Unset when the client sends no header. SessionTriggerApi: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time api_key_id: type: string format: uuid description: The API key which initiated this session. ip_address: type: string maxLength: 45 description: The IP address of the client which initiated this session. trigger_id: type: string format: uuid description: The trigger that initiated this session. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: >- Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. seed_context: type: string maxLength: 262144 nullable: true description: >- Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. SessionTriggerTime: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time trigger_id: type: string format: uuid description: The trigger that initiated this session. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: >- Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. seed_context: type: string maxLength: 262144 nullable: true description: >- Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. SessionTriggerWebhook: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time integration_webhook_id: type: string format: uuid description: The webhook that triggered this session. trigger_id: type: string format: uuid description: The webhook trigger that initiated this session. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: >- Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. remote_id: type: string maxLength: 255 nullable: true description: Remote identifier for correlating related events to this session. seed_context: type: string maxLength: 262144 nullable: true description: >- Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. securitySchemes: apiKey: type: http scheme: basic description: >- API key: key id as the username, secret as the password. An account API key carries the same scopes as an OAuth token and is checked against the scopes listed under oauth2 on each operation. A trigger API key is limited to its trigger's workspace and reaches only the session operations that list this scheme alongside the oauth2 scopes. bearerApiKey: type: http scheme: bearer bearerFormat: : description: >- The same API key as one Bearer token, `:`. An account API key carries the same scopes as an OAuth token and is checked against the scopes listed under oauth2 on each operation. A trigger API key is limited to its trigger's workspace and reaches only the session operations that list this scheme alongside the oauth2 scopes. oauth2: type: oauth2 description: >- OAuth 2.0 authorization code flow with PKCE (S256). Discovery: https://api.guild.ai/.well-known/oauth-authorization-server. flows: authorizationCode: authorizationUrl: https://api.guild.ai/v1/oauth/authorize tokenUrl: https://api.guild.ai/v1/oauth/token refreshUrl: https://api.guild.ai/v1/oauth/token scopes: agents:read: Read agents agents:write: Read and change agents sessions:read: Read sessions sessions:write: Read and change sessions workspaces:read: Read workspaces workspaces:write: Read and change workspaces skills:read: Read skills skills:write: Read and change skills integrations:read: Read integrations integrations:write: Read and change integrations applications:read: Read applications applications:write: Read and change applications organizations:read: Read organizations organizations:write: Read and change organizations ````