{ "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 and authenticated with account API keys (HTTP Basic, key id as the username and the secret as the password). See https://docs.guild.ai/api-reference/introduction for scopes and behavior. A session-events websocket also exists at wss://api.guild.ai/v1/sessions/{session_id}/events/ws with the same Basic auth on the handshake; OpenAPI cannot describe websockets, so it is not listed in paths." }, "servers": [ { "url": "https://api.guild.ai/v1", "description": "Production" } ], "tags": [ { "name": "accounts" }, { "name": "agents" }, { "name": "oauth" }, { "name": "sessions" }, { "name": "skills" }, { "name": "workspaces" } ], "paths": { "/accounts/{account_id_or_name}/skills": { "get": { "operationId": "get_account_skills", "summary": "List an account's skills", "description": "Requires `skills:read`.", "tags": [ "accounts" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "account_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "default": null, "title": "Sort By", "nullable": true, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "maximum": 1000, "minimum": 0, "title": "Limit", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "maximum": 9223372036854776000, "minimum": 0, "title": "Offset", "type": "integer" } }, { "name": "search", "in": "query", "required": false, "schema": { "default": null, "title": "Search", "nullable": true, "type": "string" } }, { "name": "archived", "in": "query", "required": false, "schema": { "default": null, "title": "Archived", "nullable": true, "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "create_account_skill", "summary": "Create a skill under an account", "description": "Requires `skills:write`. A key cannot create a *public* skill even with `skills:write` -- publishing is admin-only.", "tags": [ "accounts" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "account_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "title": "Name", "type": "string" }, "overview": { "default": null, "title": "Overview", "nullable": true, "type": "string" }, "is_public": { "default": false, "title": "Is Public", "type": "boolean" }, "avatar_url": { "default": null, "title": "Avatar Url", "nullable": true, "type": "string" } }, "required": [ "name" ], "title": "CreateAccountSkillInput", "type": "object" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } } }, "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" } } } } } } }, "/accounts/{account_id_or_name}/workspaces": { "get": { "operationId": "get_account_workspaces", "summary": "List an account's workspaces", "description": "Requires `workspaces:read`. A workspace with restricted membership (`should_restrict_members`) never appears here for an account key, regardless of scope -- that restriction narrows the workspace to its member roster, and a key can't be a member.", "tags": [ "accounts" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "account_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "default": null, "title": "Sort By", "nullable": true, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "maximum": 1000, "minimum": 0, "title": "Limit", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "maximum": 9223372036854776000, "minimum": 0, "title": "Offset", "type": "integer" } }, { "name": "archived", "in": "query", "required": false, "schema": { "default": null, "title": "Archived", "nullable": true, "type": "boolean" } }, { "name": "filter", "in": "query", "required": false, "schema": { "default": null, "title": "Filter", "nullable": true, "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "default": null, "title": "Search", "nullable": true, "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents": { "get": { "operationId": "list_agents", "summary": "List agents", "description": "No key required to see public agents. With a key holding `agents:read`, the results also include the account's own private agents.", "tags": [ "agents" ], "parameters": [ { "name": "sort_by", "in": "query", "required": false, "schema": { "default": null, "title": "Sort By", "nullable": true, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "maximum": 1000, "minimum": 0, "title": "Limit", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "maximum": 9223372036854776000, "minimum": 0, "title": "Offset", "type": "integer" } }, { "name": "search", "in": "query", "required": false, "schema": { "default": null, "title": "Search", "nullable": true, "type": "string" } }, { "name": "fast", "in": "query", "required": false, "schema": { "default": false, "title": "Fast", "type": "boolean" } }, { "name": "published_only", "in": "query", "required": false, "schema": { "default": false, "title": "Published Only", "type": "boolean" } }, { "name": "is_public", "in": "query", "required": false, "schema": { "default": false, "title": "Is Public", "type": "boolean" } }, { "name": "is_pinned", "in": "query", "required": false, "schema": { "default": null, "title": "Is Pinned", "nullable": true, "type": "boolean" } }, { "name": "for_workspace", "in": "query", "required": false, "schema": { "default": null, "title": "For Workspace", "nullable": true, "type": "string" } }, { "name": "tags", "in": "query", "required": false, "schema": { "default": null, "title": "Tags", "nullable": true, "type": "string" } }, { "name": "categories", "in": "query", "required": false, "schema": { "default": null, "title": "Categories", "nullable": true, "type": "string" } }, { "name": "agent_types", "in": "query", "required": false, "schema": { "default": null, "title": "Agent Types", "nullable": true, "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "default": null, "title": "Owner", "nullable": true, "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "create_agent", "summary": "Create an agent", "description": "Requires `agents:write`.", "tags": [ "agents" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "title": "Name", "type": "string" }, "description": { "default": null, "title": "Description", "nullable": true, "type": "string" }, "is_public": { "default": false, "title": "Is Public", "type": "boolean" }, "avatar_url": { "default": null, "title": "Avatar Url", "nullable": true, "type": "string" }, "owner_id": { "default": null, "title": "Owner Id", "nullable": true, "format": "uuid", "type": "string" }, "maintainer_id": { "default": null, "title": "Maintainer Id", "nullable": true, "format": "uuid", "type": "string" }, "category": { "default": null, "title": "Category", "nullable": true, "type": "string" }, "tags": { "default": null, "title": "Tags", "nullable": true, "items": { "type": "string" }, "type": "array" }, "forked_from_version": { "default": null, "title": "Forked From Version", "nullable": true, "format": "uuid", "type": "string" }, "template": { "default": null, "nullable": true, "$ref": "#/components/schemas/AgentCreationTemplate" } }, "required": [ "name" ], "title": "CreateAgentInput", "type": "object" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "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" } } } } } } }, "/agents/{agent_id_or_name}": { "get": { "operationId": "get_agent", "summary": "Get an agent", "description": "No key required for a public agent. A private agent needs `agents:read` on a key belonging to its owner account, or the read 404s -- a denied read looks identical to a nonexistent agent.", "tags": [ "agents" ], "parameters": [ { "name": "agent_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{agent_id_or_name}/configure-llm": { "post": { "operationId": "configure_agent_llm", "summary": "Configure an LLM agent", "description": "Requires `agents:write`. Writes a new committed version of an LLM agent from a system prompt, description, and tool list.", "tags": [ "agents" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "agent_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "system_prompt": { "title": "System Prompt", "type": "string" }, "description": { "title": "Description", "type": "string" }, "tools": { "items": { "$ref": "#/components/schemas/ConfigureLlmIntegrationToolsInput" }, "title": "Tools", "type": "array" }, "guild_tools": { "default": [], "items": { "type": "string" }, "title": "Guild Tools", "type": "array" }, "mode": { "default": "one-shot", "enum": [ "one-shot", "multi-turn" ], "title": "Mode", "type": "string" }, "summary": { "default": null, "title": "Summary", "nullable": true, "type": "string" }, "version_number": { "default": "1.0.0", "title": "Version Number", "type": "string" } }, "required": [ "system_prompt", "description", "tools" ], "title": "ConfigureAgentLlmInput", "type": "object" } } } }, "responses": { "201": { "description": "The newly committed agent version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersion" } } } }, "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" } } } }, "404": { "description": "Not found, or not visible to this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{agent_id_or_name}/versions": { "get": { "operationId": "list_agent_versions", "summary": "List an agent's versions", "tags": [ "agents" ], "parameters": [ { "name": "agent_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "maximum": 1000, "minimum": 0, "title": "Limit", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "maximum": 9223372036854776000, "minimum": 0, "title": "Offset", "type": "integer" } }, { "name": "type", "in": "query", "required": false, "schema": { "default": null, "nullable": true, "$ref": "#/components/schemas/AgentVersionType" } }, { "name": "statuses", "in": "query", "required": false, "schema": { "default": null, "title": "Statuses", "nullable": true, "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersion" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Requires `agents:read`." } }, "/me": { "get": { "operationId": "get_me", "summary": "Identify the calling key", "description": "Returns the identity of the API key making the request: the account it acts as, the key's id, and the key's scopes. Requires only a valid key; no scope is needed.", "tags": [ "accounts" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/oauth/register": { "post": { "operationId": "register_oauth_client", "summary": "Register an OAuth client", "description": "Dynamic client registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)). An MCP client registers itself before its first authorization request, so nobody has to add it by hand. This endpoint requires no authentication. Every client registered here is public: it holds no secret and proves itself on each authorization with PKCE, so registering grants nothing on its own -- the user's consent is still required. Each `redirect_uri` must use `https`, or `http` on a loopback address, and must not contain a fragment. Registration is rate-limited to 10 requests per hour per IP address. Fields a client sends that are not listed here are ignored.", "tags": [ "oauth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "RegisterOAuthClientInput", "type": "object", "required": [ "client_name", "redirect_uris" ], "properties": { "client_name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "A display name for the client." }, "redirect_uris": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "maxLength": 1024 }, "description": "Where to send the user back after authorization. An `http` loopback redirect URI matches a registered redirect URI on any port, per [RFC 8252 section 7.3](https://www.rfc-editor.org/rfc/rfc8252#section-7.3)." }, "token_endpoint_auth_method": { "type": "string", "enum": [ "none" ], "default": "none" }, "grant_types": { "type": "array", "items": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "default": [ "authorization_code", "refresh_token" ] }, "response_types": { "type": "array", "items": { "type": "string", "enum": [ "code" ] }, "default": [ "code" ] } } } } } }, "responses": { "201": { "description": "The registered client", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_id_issued_at": { "type": "integer", "description": "When the client was registered, in seconds since the Unix epoch." }, "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "type": "string" }, "grant_types": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sessions/{session_id}": { "get": { "operationId": "gen_session", "summary": "Get a session", "description": "Requires `workspaces:read`.", "tags": [ "sessions" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sessions/{session_id}/events": { "get": { "operationId": "gen_session_events", "summary": "Fetch session events", "description": "Requires `workspaces:read` and `agents:read`. Events default to newest-first (`sort_by=-id`) with a limit of 20, so a naive read returns the tail of the conversation in reverse. For polling, pass `from_id` as an exclusive cursor (`id > from_id`) so each poll returns only what happened since the last one -- event ids are UUIDv7 and therefore time-ordered. The agent's reply arrives as a `runtime_done` event whose `content.text` carries the message; events persist when a turn completes, not while the model is streaming, so a poll during generation returns nothing new until the turn finishes.\n\nA key missing `agents:read` currently gets a `500`, not a filtered `200` or a `403` -- serializing an agent task reads details the key isn't allowed to see, and that read fails loudly instead of being omitted. Grant `agents:read` alongside `workspaces:read` for any session that ran an agent.", "tags": [ "sessions" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "default": null, "title": "Sort By", "nullable": true, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "maximum": 1000, "minimum": 0, "title": "Limit", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "maximum": 9223372036854776000, "minimum": 0, "title": "Offset", "type": "integer" } }, { "name": "from_id", "in": "query", "required": false, "schema": { "default": null, "title": "From Id", "nullable": true, "type": "string" } }, { "name": "types", "in": "query", "required": false, "schema": { "default": null, "title": "Types", "nullable": true, "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "create_session_event", "summary": "Post a follow-up event to a session", "description": "Requires `sessions:write`. The message is authored by the key itself (`author.type: \"api_key\"`) -- a key may never author as anyone else. The `agent_id` field is accepted but ignored for a key, so a key cannot switch which agent answers mid-conversation; start a new session instead. A key converses only in the chat sessions it initiated -- posting into any other session (another key's chat, a person's chat, a trigger session) is `404`.", "tags": [ "sessions" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateTextSessionEventInput" }, { "$ref": "#/components/schemas/CreateJsonSessionEventInput" }, { "$ref": "#/components/schemas/CreateMultimodalSessionEventInput" }, { "$ref": "#/components/schemas/CreateMultipartSessionEventInput" } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "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" } } } } } } }, "/sessions/{session_id}/runtimes": { "get": { "operationId": "get_session_runtimes", "summary": "Fetch session runtimes", "description": "Requires `workspaces:read`.", "tags": [ "sessions" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 0, "maximum": 1000 }, "description": "Maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of items to skip before returning results." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeContainer" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sessions/{session_id}/tasks": { "get": { "operationId": "gen_session_tasks", "summary": "Fetch session sub-tasks", "description": "Requires `workspaces:read` and `agents:read` -- see the note on session events above about the `500` when `agents:read` is missing.", "tags": [ "sessions" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 0, "maximum": 1000 }, "description": "Maximum number of items to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of items to skip before returning results." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/skills/{skill_id_or_name}": { "get": { "operationId": "get_skill", "summary": "Get a skill", "description": "Requires `skills:read`.", "tags": [ "skills" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "skill_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/skills/{skill_id_or_name}/versions": { "post": { "operationId": "create_skill_version", "summary": "Create a skill version", "description": "Requires `skills:write`.", "tags": [ "skills" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "skill_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "version_number": { "title": "Version Number", "type": "string" }, "description": { "title": "Description", "type": "string" }, "body": { "maxLength": 100000, "title": "Body", "type": "string" } }, "required": [ "version_number", "description", "body" ], "title": "CreateSkillVersionInput", "type": "object" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersion" } } } }, "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" } } } } } } }, "/versions/{version_id}/publish": { "post": { "operationId": "publish_agent_version", "summary": "Publish an agent version", "description": "Requires `agents:write`.", "tags": [ "agents" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "force_publish": { "default": false, "title": "Force Publish", "type": "boolean" } }, "title": "PublishAgentVersionInput", "type": "object" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersion" } } } }, "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" } } } } } } }, "/workspace_agents/{workspace_agent_id}/credential-associations": { "get": { "operationId": "list_workspace_agent_credential_associations", "summary": "List a workspace agent's credential associations", "description": "Requires `workspaces:read`. Returns the credentials shared with the workspace agent, one row per association.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "maximum": 1000, "minimum": 0, "title": "Limit", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "maximum": 9223372036854776000, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialAssociation" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "create_workspace_agent_credential_association", "summary": "Share an existing credential with a workspace agent", "description": "Requires `integrations:write`. Creating credentials outside this dedicated mint stays human-only by design; the partner flow is admin-connects-once, key-attaches.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "auth_config_id": { "format": "uuid", "title": "Auth Config Id", "type": "string" }, "credentials_id": { "format": "uuid", "title": "Credentials Id", "type": "string" } }, "required": [ "auth_config_id", "credentials_id" ], "title": "CreateCredentialAssociationInput", "type": "object" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialAssociation" } } } }, "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" } } } } } } }, "/workspace_agents/{workspace_agent_id}/credential-associations/{association_id}": { "delete": { "operationId": "delete_workspace_agent_credential_association", "summary": "Disconnect a credential association from a workspace agent", "description": "Requires `integrations:write`. Disconnects the credential from this workspace agent; for a credential created just for this agent (rather than an existing one shared with it), deleting the association deletes that credential too. Callable by an account admin, the workspace agent's installer, or the credential's own owner.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "association_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialAssociation" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace_agents/{workspace_agent_id}/credentials/api-key": { "post": { "operationId": "connect_workspace_agent_api_key", "summary": "Mint an API-key credential for a workspace agent", "description": "Requires `integrations:write` and `workspaces:read` -- the route resolves the workspace agent before anything else, so a key missing `workspaces:read` gets `404` rather than reaching the scope check.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "owner_id", "in": "query", "required": true, "schema": { "title": "Owner Id", "type": "string" } }, { "name": "auth_config_id", "in": "query", "required": true, "schema": { "title": "Auth Config Id", "type": "string" } }, { "name": "event_id", "in": "query", "required": false, "schema": { "default": null, "title": "Event Id", "nullable": true, "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialAssociation" } } } }, "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" } } } } } } }, "/workspaces": { "post": { "operationId": "create_workspace", "summary": "Create a workspace", "description": "Requires `workspaces:write`. The key is recorded as the workspace's creator; `owner_id` must be the key's own account -- aiming at another account is `403`.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "title": "Name", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" } }, "required": [ "name", "owner_id" ], "title": "CreateWorkspaceInput", "type": "object" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "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" } } } } } } }, "/workspaces/{workspace_id_or_name}": { "get": { "operationId": "get_workspace", "summary": "Get a workspace", "description": "Requires `workspaces:read`. A workspace with restricted membership (`should_restrict_members`) is invisible to every account key regardless of scope, and returns `404`.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspaces/{workspace_id_or_name}/sessions": { "get": { "operationId": "get_workspace_sessions", "summary": "List a workspace's sessions", "description": "Requires `workspaces:read`.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "maximum": 1000, "minimum": 0, "title": "Limit", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "maximum": 9223372036854776000, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "create_workspace_session", "summary": "Start a session in a workspace", "description": "Requires `sessions:write` on a workspace the key's account owns. `chat` is the only `session_type` a key may create -- `time`, `webhook`, `api_trigger`, and `agent_test` sessions are a `403`. The key is recorded as the session's `initiator` (serialized `type: \"api_key\"`), and the agent begins executing `initial_prompt` immediately.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_type", "agent_id", "initial_prompt" ], "properties": { "session_type": { "type": "string", "enum": [ "chat" ], "description": "The only value a key may pass." }, "agent_id": { "type": "string", "format": "uuid" }, "initial_prompt": { "type": "string" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "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" } } } } } } }, "/workspaces/{workspace_id_or_name}/triggers": { "post": { "operationId": "create_trigger", "summary": "Create a trigger in a workspace", "description": "Requires `workspaces:write` and `agents:read`. A key may create `time` (schedule) triggers only -- `webhook` and `api` triggers are a `403`. `workspace_agent_id` must name an agent installed in this workspace. The key is recorded as the trigger's creator. See [Schedule triggers](/platform/schedule-triggers).", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTimeTriggerBody" } } } }, "responses": { "201": { "description": "The created trigger", "content": { "application/json": { "schema": { "type": "object" } } } }, "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" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspaces/{workspace_id_or_name}/workspace_agents": { "get": { "operationId": "get_workspace_agents", "summary": "List a workspace's installed agents", "description": "Requires `workspaces:read` and `agents:read`.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "maximum": 1000, "minimum": 0, "title": "Limit", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "maximum": 9223372036854776000, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceAgent" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "add_workspace_agent", "summary": "Add an agent to a workspace", "description": "Requires `workspaces:write`, not `agents:write` -- the workspace-agent CREATE rule delegates to the workspace's own UPDATE privacy.", "tags": [ "workspaces" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "workspace_id_or_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "agent_id": { "format": "uuid", "title": "Agent Id", "type": "string" }, "should_autoupdate": { "default": true, "title": "Should Autoupdate", "type": "boolean" }, "is_default_chat_agent": { "default": false, "title": "Is Default Chat Agent", "type": "boolean" }, "event_id": { "default": null, "title": "Event Id", "nullable": true, "format": "uuid", "type": "string" } }, "required": [ "agent_id" ], "title": "AddWorkspaceAgentInput", "type": "object" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAgent" } } } }, "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" } } } } } } } }, "components": { "schemas": { "ConfigureLlmIntegrationToolsInput": { "properties": { "integration": { "title": "Integration", "type": "string" }, "tools": { "items": { "type": "string" }, "title": "Tools", "type": "array" } }, "required": [ "integration", "tools" ], "title": "ConfigureLlmIntegrationToolsInput", "type": "object" }, "Account": { "oneOf": [ { "$ref": "#/components/schemas/Organization" }, { "$ref": "#/components/schemas/User" } ] }, "Me": { "type": "object", "properties": { "key_id": { "type": "string", "format": "uuid", "description": "The id of the API key making the request." }, "account": { "$ref": "#/components/schemas/Account" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes granted to the key, as `:` strings." } }, "required": [ "key_id", "account", "scopes" ], "title": "Me" }, "Agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "agent_type": { "type": "string", "enum": [ "GUILD_TYPESCRIPT", "GUILD_NATIVE", "GOOSE", "OPENCLAW", "LANGGRAPH" ] }, "description": { "type": "string", "description": "Manual description field. Can be empty; the effective description falls back to generated_description." }, "is_public": { "type": "boolean", "description": "Whether the asset is visible to the community or only its owner." }, "name": { "type": "string", "maxLength": 100, "description": "Unique name identifying the asset within the owner account." }, "owner_id": { "type": "string", "format": "uuid", "description": "The account that owns this entity." }, "cached_forks_count": { "type": "integer", "description": "A cached version of the forks count. Might not be up to date." }, "cached_installs_count": { "type": "integer", "description": "A cached version of the installs count. Might not be up to date." }, "cached_likes_count": { "type": "integer", "description": "A cached version of the likes count. Might not be up to date." }, "is_pinned": { "type": "boolean", "description": "If true, it means the agent is pinned on the owner's account's profile." }, "moderation_state": { "type": "string", "enum": [ "ACTIVE", "DEMOTED", "UNLISTED", "DISABLED", "TAKEN_DOWN" ], "description": "Operator-controlled moderation/curation state. Owners cannot change this; only operators can, via the hub kebab menu or ops tooling." }, "status": { "type": "string", "enum": [ "CREATED", "GIT_REPOSITORY_CREATED", "READY" ] }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "archived_by_id": { "type": "string", "format": "uuid", "nullable": true }, "avatar_url": { "type": "string", "maxLength": 255, "nullable": true }, "category_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The category this agent is sorted in." }, "creation_template": { "type": "string", "enum": [ "LLM", "AUTO_MANAGED_STATE", "BLANK", "GOOSE", "GUILD_NATIVE", "OPENCLAW", "LANGGRAPH" ], "nullable": true, "description": "If applicable, the template that was selected during the creation of this agent. Note: it doesn't mean the agent is still following the template now." }, "forked_from_id": { "type": "string", "format": "uuid", "nullable": true, "description": "If applicable, the ID of the agent version this agent was forked from." }, "generated_description": { "type": "string", "nullable": true, "description": "LLM-generated description based on agent code. Regenerated automatically on every commit." }, "maintainer_id": { "type": "string", "format": "uuid", "nullable": true, "description": "OPTIONAL. Refers to the person within an organization that is tasked with maintaining the agent." }, "archived_by": {}, "category": {}, "forks_count": { "type": "integer", "description": "Number of times this agent has been forked" }, "full_name": { "type": "string", "description": "Full agent name in format \"owner_name/agent_name\"" }, "git_url": { "type": "string", "description": "URL to the agent's git repository" }, "installs_count": { "type": "integer", "description": "Number of times this agent has been installed in workspaces" }, "is_description_autogenerated": {}, "latest_published_version": {}, "latest_version": {}, "likes_count": { "type": "integer", "description": "Number of likes this agent has received" }, "maintainer": { "type": "object", "nullable": true, "description": "Maintainer of the agent (for organization-owned agents)" }, "owner": { "$ref": "#/components/schemas/Account" }, "public_profile_url": {}, "type": {}, "viewer_can_edit": { "type": "boolean", "description": "Whether the current viewer can edit this agent" } } }, "AgentCreationTemplate": { "enum": [ "LLM", "AUTO_MANAGED_STATE", "BLANK", "GOOSE", "GUILD_NATIVE", "OPENCLAW", "LANGGRAPH" ], "title": "AgentCreationTemplate", "type": "string" }, "AgentVersion": { "oneOf": [ { "$ref": "#/components/schemas/AgentVersionCommitted" }, { "$ref": "#/components/schemas/AgentVersionEphemeral" } ] }, "AgentVersionCommitted": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "agent_id": { "type": "string", "format": "uuid" }, "author_id": { "type": "string", "format": "uuid" }, "validation_status": { "type": "string", "enum": [ "SKIPPED", "PENDING", "RUNNING", "PASSED", "FAILED" ] }, "dependencies": { "type": "object", "nullable": true, "description": "npm package.json dependencies" }, "description": { "type": "string", "nullable": true, "description": "Description for the agent extracted from the agent code." }, "env_references": { "type": "array", "items": {}, "nullable": true, "description": "Workspace variable keys referenced as {{env.KEY}} in the version's prompt, extracted at build time" }, "input_schema": { "type": "object", "nullable": true, "description": "JSON Schema from Zod input" }, "output_schema": { "type": "object", "nullable": true, "description": "JSON Schema from Zod output" }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "publishing_started_at": { "type": "string", "format": "date-time", "nullable": true }, "raw_tools": { "type": "array", "items": {}, "nullable": true, "description": "Structured per-tool metadata. Each entry is a tool object discriminated by toolType (integration, legacy, agent, builtin)." }, "runtime_environment_id": { "type": "string", "format": "uuid", "nullable": true }, "sha": { "type": "string", "maxLength": 40, "nullable": true, "description": "Git commit SHA (40-character hexadecimal). For agents: set on version creation. For integrations: set after code is stored in GitHub." }, "summary": { "type": "string", "maxLength": 500, "nullable": true, "description": "Commit message summary. For agents: set on version creation. For integrations: set after code is stored in GitHub." }, "tools": { "type": "array", "items": {}, "nullable": true }, "version_number": { "type": "string", "maxLength": 100, "nullable": true, "description": "The semantic version number (i.e., MAJOR.MINOR.PATCH) of this version" }, "agent": {}, "author": {}, "status": {}, "version_type": {} } }, "AgentVersionEphemeral": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "agent_id": { "type": "string", "format": "uuid" }, "author_id": { "type": "string", "format": "uuid" }, "files": { "type": "object", "description": "The files for this version and their content. Format: {[key: filename]: content}" }, "validation_status": { "type": "string", "enum": [ "SKIPPED", "PENDING", "RUNNING", "PASSED", "FAILED" ] }, "dependencies": { "type": "object", "nullable": true, "description": "npm package.json dependencies" }, "description": { "type": "string", "nullable": true, "description": "Description for the agent extracted from the agent code." }, "env_references": { "type": "array", "items": {}, "nullable": true, "description": "Workspace variable keys referenced as {{env.KEY}} in the version's prompt, extracted at build time" }, "input_schema": { "type": "object", "nullable": true, "description": "JSON Schema from Zod input" }, "output_schema": { "type": "object", "nullable": true, "description": "JSON Schema from Zod output" }, "raw_tools": { "type": "array", "items": {}, "nullable": true, "description": "Structured per-tool metadata. Each entry is a tool object discriminated by toolType (integration, legacy, agent, builtin)." }, "runtime_environment_id": { "type": "string", "format": "uuid", "nullable": true }, "tools": { "type": "array", "items": {}, "nullable": true }, "version_number": { "type": "string", "maxLength": 100, "nullable": true, "description": "The semantic version number (i.e., MAJOR.MINOR.PATCH) of this version" }, "agent": {}, "author": {}, "published_at": {}, "publishing_started_at": {}, "sha": {}, "status": {}, "summary": {}, "version_type": {} } }, "AgentVersionType": { "enum": [ "EPHEMERAL", "COMMITTED" ], "title": "AgentVersionType", "type": "string" }, "CreateJsonSessionEventInput": { "properties": { "agent_id": { "default": null, "title": "Agent Id", "nullable": true, "type": "string" }, "selected_skills": { "default": null, "title": "Selected Skills", "nullable": true, "items": { "type": "string" }, "type": "array" }, "content": { "additionalProperties": true, "title": "Content", "type": "object" }, "mode": { "title": "Mode", "type": "string", "enum": [ "json" ] } }, "required": [ "content", "mode" ], "title": "CreateJsonSessionEventInput", "type": "object" }, "CreateMultimodalSessionEventInput": { "properties": { "agent_id": { "default": null, "title": "Agent Id", "nullable": true, "type": "string" }, "selected_skills": { "default": null, "title": "Selected Skills", "nullable": true, "items": { "type": "string" }, "type": "array" }, "content": { "items": { "$ref": "#/components/schemas/_MultimodalContentPart" }, "minItems": 1, "title": "Content", "type": "array" }, "mode": { "title": "Mode", "type": "string", "enum": [ "multimodal" ] } }, "required": [ "content", "mode" ], "title": "CreateMultimodalSessionEventInput", "type": "object" }, "CreateMultipartSessionEventInput": { "properties": { "agent_id": { "default": null, "title": "Agent Id", "nullable": true, "type": "string" }, "selected_skills": { "default": null, "title": "Selected Skills", "nullable": true, "items": { "type": "string" }, "type": "array" }, "content": { "additionalProperties": true, "title": "Content", "type": "object" }, "mode": { "title": "Mode", "type": "string", "enum": [ "multipart" ] } }, "required": [ "content", "mode" ], "title": "CreateMultipartSessionEventInput", "type": "object" }, "CreateTextSessionEventInput": { "properties": { "agent_id": { "default": null, "title": "Agent Id", "nullable": true, "type": "string" }, "selected_skills": { "default": null, "title": "Selected Skills", "nullable": true, "items": { "type": "string" }, "type": "array" }, "content": { "title": "Content", "type": "string" }, "mode": { "default": "text", "title": "Mode", "type": "string", "enum": [ "text" ] } }, "required": [ "content" ], "title": "CreateTextSessionEventInput", "type": "object" }, "CreateTimeTriggerBody": { "title": "CreateTimeTriggerBody", "type": "object", "required": [ "workspace_agent_id", "type", "frequency", "agent_input" ], "properties": { "workspace_agent_id": { "type": "string", "format": "uuid", "description": "The installed workspace agent the trigger runs." }, "type": { "type": "string", "enum": [ "time" ] }, "frequency": { "$ref": "#/components/schemas/TimeTriggerFrequency" }, "agent_input": { "type": "object", "additionalProperties": true, "description": "The fixed input the agent receives each time the trigger fires." }, "time_of_day": { "type": "string", "nullable": true, "description": "Time of day in ISO format, such as `09:00`. Used by `DAILY`, `WEEKLY`, and `MONTHLY`." }, "days_of_week": { "type": "string", "nullable": true, "description": "Comma-separated day names, such as `monday,thursday`. Used by `WEEKLY`." }, "days_of_month": { "type": "string", "nullable": true, "description": "Comma-separated days from `1` to `31`, or `-1` for the last day of the month. Used by `MONTHLY`." }, "minutes_of_hour": { "type": "string", "nullable": true, "description": "Comma-separated minutes from `0` to `59`." }, "cron_expression": { "type": "string", "nullable": true, "description": "A five-field cron expression, such as `0 9 * * 1-5`. Required for `CRON` and rejected for other frequencies." }, "cron_timezone": { "type": "string", "nullable": true, "description": "An IANA timezone name for `cron_expression`, such as `America/Los_Angeles`. Valid only for `CRON`." } } }, "CredentialAssociation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "auth_config_id": { "type": "string", "format": "uuid", "description": "Integration auth config this row applies to" }, "created_by_id": { "type": "string", "format": "uuid", "description": "The user or API key that granted this credential to the agent." }, "target_id": { "type": "string", "format": "uuid", "description": "Workspace agent install receiving the credential; the association is scoped to this install's workspace. Account-wide availability is plain credential ownership with no association row." }, "kind": { "type": "string", "enum": [ "CONNECTED", "GRANTED" ], "description": "GRANTED = existing credential shared with the agent; CONNECTED = credential created for the agent (connect flow)." }, "credentials_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Linked credential row; null while OAuth connect is pending." }, "integration": {}, "member_owned": {}, "owner": {}, "workspace": {}, "workspace_agent_id": {} } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "Event": { "oneOf": [ { "$ref": "#/components/schemas/EventContainerLog" }, { "$ref": "#/components/schemas/EventAgentConsole" }, { "$ref": "#/components/schemas/EventAgentInstallRequest" }, { "$ref": "#/components/schemas/EventAgentNotificationError" }, { "$ref": "#/components/schemas/EventAgentNotificationMessage" }, { "$ref": "#/components/schemas/EventAgentNotificationProgress" }, { "$ref": "#/components/schemas/EventCredentialsRequest" }, { "$ref": "#/components/schemas/EventInterrupted" }, { "$ref": "#/components/schemas/EventLlmDone" }, { "$ref": "#/components/schemas/EventLlmStart" }, { "$ref": "#/components/schemas/EventRuntimeDone" }, { "$ref": "#/components/schemas/EventRuntimeError" }, { "$ref": "#/components/schemas/EventRuntimeRunning" }, { "$ref": "#/components/schemas/EventRuntimeStart" }, { "$ref": "#/components/schemas/EventRuntimeWaiting" }, { "$ref": "#/components/schemas/EventSecurity" }, { "$ref": "#/components/schemas/EventSystemError" }, { "$ref": "#/components/schemas/EventSystemMessage" }, { "$ref": "#/components/schemas/EventTriggerMessage" }, { "$ref": "#/components/schemas/EventUserMessage" } ] }, "EventAgentConsole": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "string" }, "level": { "type": "string", "enum": [ "DEBUG", "INFO", "WARN", "ERROR" ] }, "task_id": { "type": "string", "format": "uuid" }, "type": {} } }, "EventAgentInstallRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "requested_agent_id": { "type": "string", "format": "uuid", "description": "The agent requested to be installed" }, "task_id": { "type": "string", "format": "uuid" }, "installed_agent_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The workspace agent created when this request was fulfilled" }, "processed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "If the request has been declined, this is when it happened." }, "processed_by_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The user who declined or accepted this request, if applicable." }, "agent": {}, "installed_agent": {}, "is_fulfilled": {}, "requested_agent": {}, "type": {} } }, "EventAgentNotificationError": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object" }, "task_id": { "type": "string", "format": "uuid" }, "data": {}, "type": {} } }, "EventAgentNotificationMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object" }, "task_id": { "type": "string", "format": "uuid" }, "type": {} } }, "EventAgentNotificationProgress": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object" }, "task_id": { "type": "string", "format": "uuid" }, "type": {} } }, "EventContainerLog": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "task_id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "INFO", "ERROR" ], "nullable": true, "description": "Severity of the line: INFO for ordinary output, ERROR for error-level output. Nullable for now; pre-existing rows have no level." }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the line was produced in the container (not received)" }, "type": {} } }, "EventCredentialsRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "auth_config_id": { "type": "string", "format": "uuid", "description": "The auth config this credentials should use" }, "task_id": { "type": "string", "format": "uuid" }, "is_fulfilled": { "type": "boolean", "description": "Indicates whether the request has been fulfilled. Skipped requests are also marked fulfilled (see skipped_at). If it is set to true, credentials is null, and skipped_at is null, it means the credentials has been deleted later." }, "credentials_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The credentials created when this request was fulfilled" }, "skipped_at": { "type": "string", "format": "date-time", "nullable": true, "description": "If the request was skipped, when it happened." }, "skipped_by_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The user who skipped this request, if applicable." }, "target_account_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The account the credentials should be installed in, if applicable. This is used by The Smith to request installs in other accounts." }, "agent": {}, "integration": {}, "target_account": {}, "type": {} } }, "EventInterrupted": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "interrupted_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was interrupted" }, "interrupted_by_id": { "type": "string", "format": "uuid", "description": "User who interrupted the session" }, "task_id": { "type": "string", "format": "uuid" }, "interrupted_by": {}, "type": {} } }, "EventLlmDone": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "body": { "type": "string" }, "headers": { "type": "object" }, "llm_event_id": { "type": "string", "format": "uuid" }, "status_code": { "type": "integer" }, "task_id": { "type": "string", "format": "uuid" }, "type": {} } }, "EventLlmStart": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "headers": { "type": "object" }, "inference_provider_id": { "type": "string", "format": "uuid" }, "llm_provider": { "type": "string", "enum": [ "ANTHROPIC", "OPENAI", "GEMINI", "FAKE_LLM", "META" ] }, "payload": { "type": "object" }, "task_id": { "type": "string", "format": "uuid" }, "llm_model": { "type": "string", "maxLength": 100, "nullable": true }, "model": {}, "provider": {}, "type": {} } }, "EventRuntimeDone": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object" }, "task_id": { "type": "string", "format": "uuid" }, "type": {} } }, "EventRuntimeError": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "string" }, "task_id": { "type": "string", "format": "uuid" }, "stack": { "type": "string", "nullable": true }, "type": {} } }, "EventRuntimeRunning": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "task_id": { "type": "string", "format": "uuid" }, "type": {} } }, "EventRuntimeStart": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object" }, "task_id": { "type": "string", "format": "uuid" }, "type": {} } }, "EventRuntimeWaiting": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "task_id": { "type": "string", "format": "uuid" }, "type": {} } }, "EventSecurity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "decision": { "type": "string", "enum": [ "ALLOW", "DENY", "ERROR" ], "description": "Security decision outcome." }, "message": { "type": "string", "description": "Human-readable security event summary." }, "operation": { "type": "string", "maxLength": 255, "description": "Integration operation or action evaluated." }, "reason_code": { "type": "string", "enum": [ "POLICY_DENIED", "CREDENTIAL_UNAVAILABLE", "PRIVILEGE_ESCALATION_DENIED", "PLATFORM_ACCESS_DENIED", "ACCESS_ALLOWED" ], "description": "Stable machine code for why the decision occurred." }, "task_id": { "type": "string", "format": "uuid" }, "acting_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Human acting on behalf of the task when the decision was recorded." }, "capability": { "type": "string", "maxLength": 32, "nullable": true, "description": "Capability evaluated for this decision (read, write, delete, admin)." }, "credentials_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Credentials involved in the security decision when applicable." }, "details": { "type": "object", "nullable": true, "description": "Optional structured audit context beyond task/session links." }, "acting_user": {}, "credentials": {}, "integration": {}, "task": {}, "type": {} } }, "EventSystemError": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "details": { "type": "object", "description": "An arbitrary JSON object that stores details about the error." }, "message": { "type": "string", "description": "A user-visible message that describes the error that occurred." }, "task_id": { "type": "string", "format": "uuid" }, "content": {}, "data": {}, "type": {} } }, "EventSystemMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object" }, "task_id": { "type": "string", "format": "uuid" }, "data": {}, "type": {} } }, "EventTriggerMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object" }, "task_id": { "type": "string", "format": "uuid" }, "data": {}, "type": {} } }, "EventUserMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "author_id": { "type": "string", "format": "uuid", "description": "Who sent this message: a user, or an account API key relaying a conversation on behalf of its account." }, "content": { "type": "array", "items": {} }, "task_id": { "type": "string", "format": "uuid" }, "author": {}, "content_parts": {}, "type": {} } }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "creator_id": { "type": "string", "format": "uuid", "description": "The user who created this organization. Note that this does not give that user membership." }, "name": { "type": "string", "maxLength": 100, "description": "The unique name identifying this account." }, "cached_forks_count": { "type": "integer", "description": "A cached version of the forks count. Might not be up to date." }, "cached_forks_public_count": { "type": "integer", "description": "A cached version of the forks count for public agents. Might not be up to date." }, "cached_installs_count": { "type": "integer", "description": "A cached version of the installs count. Might not be up to date." }, "cached_installs_public_count": { "type": "integer", "description": "A cached version of the installs count for public agents. Might not be up to date." }, "cached_likes_count": { "type": "integer", "description": "A cached version of the likes count. Might not be up to date." }, "cached_likes_public_count": { "type": "integer", "description": "A cached version of the likes count for public agents. Might not be up to date." }, "avatar_url": { "type": "string", "maxLength": 255, "nullable": true }, "banner_url": { "type": "string", "maxLength": 255, "nullable": true }, "bio": { "type": "string", "nullable": true }, "discord_url": { "type": "string", "maxLength": 255, "nullable": true }, "email_domain": { "type": "string", "maxLength": 100, "nullable": true, "description": "The email domain of the organization. Members will be automatically invited to this organization if they have an email with this domain." }, "full_name": { "type": "string", "maxLength": 100, "nullable": true, "description": "The display name of the account." }, "github_url": { "type": "string", "maxLength": 255, "nullable": true }, "linkedin_url": { "type": "string", "maxLength": 255, "nullable": true }, "threads_url": { "type": "string", "maxLength": 255, "nullable": true }, "website_url": { "type": "string", "maxLength": 255, "nullable": true }, "x_url": { "type": "string", "maxLength": 255, "nullable": true }, "youtube_url": { "type": "string", "maxLength": 255, "nullable": true }, "member_count": {}, "viewer_membership_id": {}, "viewer_membership_public": {}, "viewer_role": { "type": "string", "enum": [ "ADMIN", "MEMBER" ], "nullable": true, "description": "Current viewer's role in the organization (null if not a member)" }, "type": { "type": "string", "enum": [ "organization" ], "description": "Account type, always \"organization\"" } } }, "RuntimeContainer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "base_path": { "type": "string", "maxLength": 255, "description": "The base path on which the runtime's web server is exposed. Guildcore will call // " }, "created_by_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "locked_for_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "If set, only tasks in that specific session can use the runtime container, otherwise it can be shared within the workspace." }, "container_id": {}, "created_by": {}, "destroyed_at": {}, "image": {}, "started_at": {}, "status": {}, "workspace": {} } }, "Session": { "oneOf": [ { "$ref": "#/components/schemas/SessionAgentTest" }, { "$ref": "#/components/schemas/SessionChat" }, { "$ref": "#/components/schemas/SessionTriggerApi" }, { "$ref": "#/components/schemas/SessionTriggerTime" }, { "$ref": "#/components/schemas/SessionTriggerWebhook" } ] }, "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": "The user who started this agent test session." }, "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", "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." }, "seed_context": { "type": "string", "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." } } }, "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", "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." }, "session_type": {}, "trigger": {} } }, "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", "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", "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." } } }, "Skill": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_public": { "type": "boolean", "description": "Whether the asset is visible to the community or only its owner." }, "name": { "type": "string", "maxLength": 100, "description": "Unique name identifying the asset within the owner account." }, "owner_id": { "type": "string", "format": "uuid", "description": "The account that owns this entity." }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "archived_by_id": { "type": "string", "format": "uuid", "nullable": true }, "avatar_url": { "type": "string", "maxLength": 255, "nullable": true }, "overview": { "type": "string", "nullable": true, "description": "Optional human-facing overview for display and indexing. Falls back to the latest version description if not set." }, "archived_by": {}, "full_name": {}, "latest_version": {}, "likes_count": {}, "owner": {}, "type": {}, "viewer_can_edit": {} } }, "SkillVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "author_id": { "type": "string", "format": "uuid", "description": "The user or API key that created this skill version." }, "body": { "type": "string", "description": "Full markdown content for this skill version." }, "description": { "type": "string", "description": "Runtime-facing description that tells the LLM when to activate this skill." }, "skill_id": { "type": "string", "format": "uuid", "description": "The skill this version belongs to." }, "version_number": { "type": "string", "maxLength": 100, "description": "The semantic version number (MAJOR.MINOR.PATCH)." }, "author": {}, "skill": {}, "type": {} } }, "Task": { "oneOf": [ { "$ref": "#/components/schemas/TaskAgent" }, { "$ref": "#/components/schemas/TaskTool" } ] }, "TaskAgent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "CREATED", "DISPATCHED", "STARTED", "RUNNING", "WAITING", "ERROR", "DONE", "INTERRUPTED" ] }, "notified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time when this task output was sent to the runtime.\n This should be None if the task is not DONE or ERROR, or if the\n runtime hasn't been resumed yet." }, "parent_task_id": { "type": "string", "format": "uuid", "nullable": true }, "runtime_id": { "type": "string", "format": "uuid", "nullable": true, "description": "An optional runtime, if the agent is not run in the default Guild runtime." }, "saved_state": { "type": "string", "nullable": true }, "span_id": { "nullable": true, "description": "Span id of the single invoke_agent span that covers this agent task across all of its start/resume executions." }, "trace_id": { "nullable": true }, "version_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The version of the agent that this task is running. If None, it means we're running the assistant." }, "agent": {}, "cache_read_tokens": {}, "cache_write_tokens": {}, "input_tokens": {}, "llm_call_count": {}, "output_tokens": {}, "parent_task": {}, "token_usage": {}, "total_tokens": {}, "version": {} } }, "TaskTool": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "parent_task_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "CREATED", "DISPATCHED", "STARTED", "RUNNING", "WAITING", "ERROR", "DONE", "INTERRUPTED" ] }, "tool_call_id": { "type": "string" }, "tool_name": { "type": "string", "maxLength": 255 }, "http_status_code": { "type": "integer", "nullable": true, "description": "The HTTP response code of the response" }, "notified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time when this task output was sent to the runtime.\n This should be None if the task is not DONE or ERROR, or if the\n runtime hasn't been resumed yet." }, "request_bytes": { "type": "integer", "nullable": true, "description": "The number of bytes in the outgoing request" }, "response_bytes": { "type": "integer", "nullable": true, "description": "The number of bytes in the response" }, "response_data": { "type": "string", "nullable": true, "description": "Full JSON response body, stored only when the response was projected due to size" }, "parent_task": {}, "token_usage": {} } }, "TimeTriggerFrequency": { "title": "TimeTriggerFrequency", "type": "string", "enum": [ "HOURLY", "DAILY", "WEEKLY", "MONTHLY", "CRON" ] }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "email": { "type": "string", "maxLength": 100 }, "name": { "type": "string", "maxLength": 100, "description": "The unique name identifying this account." }, "cached_forks_count": { "type": "integer", "description": "A cached version of the forks count. Might not be up to date." }, "cached_forks_public_count": { "type": "integer", "description": "A cached version of the forks count for public agents. Might not be up to date." }, "cached_installs_count": { "type": "integer", "description": "A cached version of the installs count. Might not be up to date." }, "cached_installs_public_count": { "type": "integer", "description": "A cached version of the installs count for public agents. Might not be up to date." }, "cached_likes_count": { "type": "integer", "description": "A cached version of the likes count. Might not be up to date." }, "cached_likes_public_count": { "type": "integer", "description": "A cached version of the likes count for public agents. Might not be up to date." }, "is_operator": { "type": "boolean", "description": "Whether or not the user is a Guild employee (or operator). BE VERY CAREFUL WITH THIS." }, "notification_email_level": { "type": "string", "enum": [ "NONE", "IMPORTANT", "ALL" ], "description": "NONE = no emails, IMPORTANT = invitations and agent-ask only, ALL = all notification types." }, "avatar_url": { "type": "string", "maxLength": 255, "nullable": true }, "banner_url": { "type": "string", "maxLength": 255, "nullable": true }, "bio": { "type": "string", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Set when an operator closes the account. A closed user cannot start a login session by any method." }, "discord_url": { "type": "string", "maxLength": 255, "nullable": true }, "full_name": { "type": "string", "maxLength": 100, "nullable": true, "description": "The display name of the account." }, "github_url": { "type": "string", "maxLength": 255, "nullable": true }, "hubspot_synced_at": { "type": "string", "format": "date-time", "nullable": true }, "linkedin_url": { "type": "string", "maxLength": 255, "nullable": true }, "threads_url": { "type": "string", "maxLength": 255, "nullable": true }, "username_set_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Set when the user picks their username during onboarding. Once set, the username cannot be changed." }, "website_url": { "type": "string", "maxLength": 255, "nullable": true }, "x_url": { "type": "string", "maxLength": 255, "nullable": true }, "youtube_url": { "type": "string", "maxLength": 255, "nullable": true }, "type": { "type": "string", "enum": [ "user" ], "description": "Account type, always \"user\"" } } }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "creator_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 100 }, "owner_id": { "type": "string", "format": "uuid", "description": "The account that owns this entity." }, "restrict_account_credentials": { "type": "boolean", "description": "When true, tasks in this workspace may not fall back to the owning account's shared credential pool: a resolution that would reach the account default is refused so the workspace must rely on credentials granted or connected to its agents." }, "should_restrict_members": { "type": "boolean", "description": "When true, only workspace members (plus org admins of the owning org) can access this workspace; when false, it is open to the whole owning org." }, "unlimited_power_mode": { "type": "boolean", "description": "When true, this workspace's execution-tree fan-out limits are raised to the platform ceilings instead of the default budgets. The limits are raised, not removed. https://i.ibb.co/5XsvmfKg/CFD5-C99-C-B322-46-A2-9892-AFDF484-D28-E1-1.webp" }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "archived_by_id": { "type": "string", "format": "uuid", "nullable": true }, "required_credentials_mode": { "type": "string", "enum": [ "SHARED", "MEMBER" ], "nullable": true, "description": "Whose credentials agents in this workspace may run with: SHARED = only org-side credentials serve, MEMBER = only the acting member's own. Unset = no requirement. A workspace agent's own declaration overrides this one." }, "archived_by": {}, "creator": {}, "full_name": { "type": "string", "description": "Full workspace name in format \"owner_name~workspace_name\"" }, "is_viewer_member": {}, "members_enabled": {}, "owner": { "$ref": "#/components/schemas/Account" }, "unlimited_power_mode_enabled": {} } }, "WorkspaceAgent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "creator_id": { "type": "string", "format": "uuid", "description": "The user or API key that added this agent version to the workspace." }, "version_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "is_default_chat_agent": { "type": "boolean", "description": "If True, this workspace agent is used for new chat sessions when no explicit agent is provided." }, "should_autoupdate": { "type": "boolean", "description": "If True, the agent will automatically update when a new version is published." }, "required_credentials_mode": { "type": "string", "enum": [ "SHARED", "MEMBER" ], "nullable": true, "description": "Whose credentials this agent may run with: SHARED = only org-side credentials serve, MEMBER = only the acting member's own. Unset = the workspace's declaration applies, and no requirement when that is unset too." }, "agent": { "$ref": "#/components/schemas/Agent" }, "agent_version": { "$ref": "#/components/schemas/AgentVersion" }, "creator": { "$ref": "#/components/schemas/User" }, "workspace": { "$ref": "#/components/schemas/Workspace" } } }, "_AttachmentContentPart": { "properties": { "type": { "enum": [ "image", "file" ], "title": "Type", "type": "string" }, "attachment_id": { "format": "uuid", "title": "Attachment Id", "type": "string" } }, "required": [ "type", "attachment_id" ], "title": "_AttachmentContentPart", "type": "object" }, "_MultimodalContentPart": { "discriminator": { "mapping": { "file": "#/components/schemas/_AttachmentContentPart", "image": "#/components/schemas/_AttachmentContentPart", "text": "#/components/schemas/_TextContentPart" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/_TextContentPart" }, { "$ref": "#/components/schemas/_AttachmentContentPart" } ] }, "_TextContentPart": { "properties": { "type": { "title": "Type", "type": "string", "enum": [ "text" ] }, "text": { "title": "Text", "type": "string" } }, "required": [ "type", "text" ], "title": "_TextContentPart", "type": "object" } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "basic", "description": "Account API key: key id as the username, secret as the password." } } } }