openapi: 3.0.3 info: title: Guild Public API version: 1.0.0 description: 'The Guild public API, served at https://api.guild.ai/v1. Authenticate with an account API key, sent as HTTP Basic (key id as the username, secret as the password) or as a Bearer token `:`, or with an OAuth 2.0 access token. Each operation lists the credentials it accepts and the scopes it needs; see https://docs.guild.ai/api-reference/introduction#scopes. Versions are path integers and v1 is the only one: a breaking change ships as a new version rather than changing v1. Lists page with `limit` and `offset` and report `pagination.has_more`. A session-events websocket also exists at wss://api.guild.ai/v1/sessions/{session_id}/events/ws with the same credentials on the handshake; OpenAPI cannot describe websockets, so it is not listed in paths.' servers: - url: https://api.guild.ai/v1 description: Production tags: - name: accounts - name: agents - name: integrations - name: other - name: sessions - name: skills - name: triggers - name: workspaces paths: /accounts/{account_id_or_name}/credentials: get: operationId: get_account_credentials summary: List an account's integration credentials tags: - accounts security: - apiKey: [] - bearerApiKey: [] - oauth2: - integrations:read parameters: - name: account_id_or_name in: path required: true schema: type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: integration in: query required: false schema: default: null title: Integration nullable: true type: string - name: search in: query required: false schema: default: null title: Search nullable: true type: string - name: workspace_id in: query required: false schema: default: null title: Workspace Id nullable: true type: string - name: scope in: query required: false schema: default: null title: Scope nullable: true type: boolean - name: grant_candidates in: query required: false schema: default: null title: Grant Candidates nullable: true type: boolean responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/IntegrationCredentials' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /accounts/{account_id_or_name}/skills: get: operationId: get_account_skills summary: List an account's skills tags: - accounts security: - apiKey: [] - bearerApiKey: [] - oauth2: - skills:read parameters: - name: account_id_or_name in: path required: true schema: type: string - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - 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: $ref: '#/components/schemas/Pagination' '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 `skills:read`. post: operationId: create_account_skill summary: Create a skill owned by an account tags: - accounts security: - apiKey: [] - bearerApiKey: [] - oauth2: - skills:write parameters: - name: account_id_or_name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: properties: name: description: Skill name title: Name type: string overview: default: null description: What the skill is for 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' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Requires `skills:write`. A key cannot create a *public* skill even with `skills:write` -- publishing is admin-only. /accounts/{account_id_or_name}/workspaces: get: operationId: get_account_workspaces summary: List an account's workspaces tags: - accounts security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read parameters: - name: account_id_or_name in: path required: true schema: type: string - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - 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: $ref: '#/components/schemas/WorkspaceList' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-guild-response-model: WorkspaceList 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. /agents: get: operationId: list_agents summary: List and search agents tags: - agents parameters: - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: search in: query required: false schema: default: null description: Words to match in name or description 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 description: Owning user or organization, by name or ID. Omit for every agent you can see. title: Owner nullable: true type: string - name: contributor in: query required: false schema: default: null title: Contributor nullable: true type: string description: Filter the list to items created, maintained, or authored by the specified user. responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Agent' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - {} - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read description: No key required to see public agents. With a key holding `agents:read`, the results also include the account's own private agents. post: operationId: create_agent summary: Create an agent tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:write requestBody: required: true content: application/json: schema: properties: name: description: Agent name, e.g. splunk-fixer title: Name type: string description: default: null description: What the agent does 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 description: Owning user or organization, by name or ID. Omit for your own. title: Owner Id nullable: true 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 enum: - LLM - AUTO_MANAGED_STATE - BLANK - GOOSE - GUILD_NATIVE - OPENCLAW - LANGGRAPH - ADK title: AgentCreationTemplate type: string required: - name title: CreateAgentInput type: object responses: '201': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Agent' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Requires `agents:write`. /agents/{agent_id_or_name}: get: operationId: get_agent summary: Get an 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' security: - {} - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read 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. patch: operationId: update_agent summary: Update an agent's visibility, archive state or pin tags: - agents security: - oauth2: - agents:write parameters: - name: agent_id_or_name in: path required: true schema: type: string requestBody: required: false content: application/json: schema: properties: is_public: default: null title: Is Public nullable: true type: boolean is_archived: default: null title: Is Archived nullable: true type: boolean is_pinned: default: null title: Is Pinned nullable: true type: boolean avatar_url: default: null title: Avatar Url nullable: true type: string maintainer_id: default: null title: Maintainer Id nullable: true format: uuid type: string category: default: null description: Category ID or name title: Category nullable: true type: string tags: default: null description: Tag names; tags other than Guild's need a category title: Tags nullable: true items: type: string type: array title: UpdateAgentInput type: object responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Agent' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request 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: Commit a new version of an LLM agent with the given tools tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:write parameters: - name: agent_id_or_name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: properties: system_prompt: description: How the agent should behave title: System Prompt type: string description: description: What the agent does, shown to people choosing an agent title: Description type: string tools: description: 'Integration tools the agent may call, e.g. [{"integration": "github", "tools": ["github_issues_get"]}]' items: $ref: '#/components/schemas/ConfigureLlmIntegrationToolsInput' title: Tools type: array guild_tools: description: Built-in Guild tools the agent may call, e.g. ["guild_search_agent"] items: type: string title: Guild Tools type: array mode: default: one-shot description: One-shot answers once; multi-turn keeps a conversation (default one-shot) enum: - one-shot - multi-turn title: Mode type: string summary: default: null description: What changed 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/AgentVersionWithJob' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Requires `agents:write`. Writes a new committed version of an LLM agent from a system prompt, description, and tool list. /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 - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: type in: query required: false schema: default: null nullable: true enum: - EPHEMERAL - COMMITTED title: AgentVersionType type: string - 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: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - {} - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read description: Requires `agents:read`. Also reachable with an OAuth user token that holds `agents:read`; a token without it gets a `404` on a private agent. post: operationId: create_agent_version summary: Create an agent version tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:write parameters: - name: agent_id_or_name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: properties: version_type: $ref: '#/components/schemas/AgentVersionType' skip_validation: default: false title: Skip Validation type: boolean publish: default: false description: Publish the version once it passes validation title: Publish type: boolean files: default: null description: Every source file of the new version, as path and content title: Files nullable: true items: $ref: '#/components/schemas/AgentVersionFile' type: array bundle: default: null title: Bundle nullable: true type: string encoding: default: null title: Encoding nullable: true type: string commit_sha: default: null title: Commit Sha nullable: true type: string summary: default: null description: What changed title: Summary nullable: true type: string version_number: default: null title: Version Number nullable: true type: string required: - version_type title: CreateAgentVersionInput type: object responses: '201': description: Successful response content: application/json: schema: $ref: '#/components/schemas/AgentVersionWithJob' links: ValidationJob: operationId: get_validation_job parameters: version_id: $response.body#/id description: When the response has a job_id, poll the new version's validation until its status is final. Skipping validation creates no job. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/AgentVersionWithJob' /agents/{agent_id_or_name}/versions/{version_id}/revalidate: post: operationId: post_revalidate_version summary: Revalidate a version tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:write parameters: - name: agent_id_or_name in: path required: true schema: type: string - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/AgentVersionWithJob' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /customer_connectors/enroll: post: operationId: enroll_connector summary: Enroll a customer connector and issue its credentials tags: - connectors security: - connectorToken: [] requestBody: required: true content: application/json: schema: additionalProperties: false properties: request_id: format: uuid title: Request Id type: string required: - request_id title: EnrollmentInput type: object responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/CredentialResult' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-guild-response-model: CredentialResult /customer_connectors/renew: post: operationId: renew_connector summary: Renew an enrolled customer connector's credentials tags: - connectors security: - connectorToken: [] responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/CredentialResult' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-guild-response-model: CredentialResult /integrations/{integration_id_or_name}/tools: get: operationId: list_integration_tools summary: List the tools an integration provides tags: - integrations security: - apiKey: [] - bearerApiKey: [] - oauth2: - integrations:read parameters: - name: integration_id_or_name in: path required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: type: object '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /me: get: operationId: get_public_me summary: Get the identity of the calling credential description: An API key gets its own record, including the name of the account that owns it. An OAuth token gets the user it acts as, the client that holds it, and the scopes it was granted. tags: - accounts security: - apiKey: [] - bearerApiKey: [] - oauth2: [] responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PublicMe' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-guild-response-model: PublicMe /me/email-invitations: get: operationId: get_my_email_invitations summary: List organization invitations sent to the current user's email description: These are organization invitations sent to the user's email address, which can be accepted at sign-up. Returns pending invitations unless ``status`` asks for another status. tags: - accounts security: - oauth2: - organizations:read parameters: - name: status in: query required: false schema: default: null title: Status nullable: true type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/InvitationOrganization' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /me/invitations: get: operationId: list_my_invitations summary: List organization invitations sent to the current user tags: - accounts security: - oauth2: - organizations:read parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: status in: query required: false schema: default: null title: Status nullable: true type: string responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/InvitationOrganization' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /me/organizations: get: operationId: list_organizations summary: List the current user's organization memberships tags: - accounts security: - oauth2: - organizations:read parameters: - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - 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/OrganizationMembership' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /me/workspaces: get: operationId: get_my_workspaces summary: List the current user's workspaces tags: - workspaces security: - oauth2: - workspaces:read parameters: - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: owner in: query required: false schema: default: null title: Owner nullable: true format: uuid type: string - name: filter in: query required: false schema: default: null description: '''my'' for the user''s own workspaces (default), ''all'' to add their organizations''' title: Filter nullable: true enum: - my - all type: string - name: for_agent in: query required: false schema: default: null title: For Agent nullable: true type: string - name: archived in: query required: false schema: default: null title: Archived nullable: true type: boolean - 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: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /oauth/authorize: get: operationId: oauth_authorize_entry summary: Start an OAuth authorization by redirecting to the consent page tags: - oauth responses: '200': description: Successful response content: application/json: schema: type: object '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /oauth/register: post: operationId: oauth_register summary: Register an OAuth client tags: - oauth requestBody: required: true content: application/json: schema: description: |- The RFC 7591 fields this server honors; any others a client sends are ignored, as the RFC allows. properties: client_name: maxLength: 128 minLength: 1 title: Client Name type: string redirect_uris: items: type: string maxItems: 5 minItems: 1 title: Redirect Uris type: array token_endpoint_auth_method: default: none title: Token Endpoint Auth Method type: string enum: - none grant_types: default: - authorization_code - refresh_token items: enum: - authorization_code - refresh_token type: string title: Grant Types type: array response_types: default: - code items: type: string enum: - code title: Response Types type: array required: - client_name - redirect_uris title: RegisterClientInput type: object 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 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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.' /oauth/token: post: operationId: oauth_token summary: Exchange an authorization code or refresh token for an access token tags: - oauth responses: '200': description: Successful response content: application/json: schema: type: object '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /organizations/{org_id_or_name}: get: operationId: get_organization summary: Get an organization tags: - accounts security: - oauth2: - organizations:read parameters: - name: org_id_or_name in: path required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Organization' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /organizations/{org_id_or_name}/invitations: get: operationId: get_organization_invitations summary: List an organization's invitations tags: - accounts security: - oauth2: - organizations:read parameters: - name: org_id_or_name in: path required: true schema: type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: status in: query required: false schema: default: null title: Status nullable: true type: string responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/InvitationOrganization' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /organizations/{org_id_or_name}/members: get: operationId: get_organization_members summary: List an organization's members as users tags: - accounts security: - oauth2: - organizations:read parameters: - name: org_id_or_name in: path required: true schema: type: string - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - 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/OrganizationMembership' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /organizations/{org_id_or_name}/memberships: get: operationId: get_organization_memberships summary: List an organization's memberships tags: - accounts security: - oauth2: - organizations:read parameters: - name: org_id_or_name in: path required: true schema: type: string - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: search in: query required: false schema: default: null description: Filter members by name 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/OrganizationMembership' pagination: $ref: '#/components/schemas/Pagination' '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}: get: operationId: gen_session summary: Get a session tags: - sessions security: - apiKey: [] - bearerApiKey: [] - oauth2: - sessions:read 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' description: Requires `workspaces:read`. /sessions/{session_id}/events: get: operationId: gen_session_events summary: List session events tags: - sessions security: - apiKey: [] - bearerApiKey: [] - oauth2: - sessions:read parameters: - name: session_id in: path required: true schema: type: string format: uuid - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: from_id in: query required: false schema: default: null description: Only events after this event ID, e.g. the message you sent 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: $ref: '#/components/schemas/Pagination' '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 `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. A 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. post: operationId: create_session_event summary: Send a message to a session tags: - sessions security: - apiKey: [] - bearerApiKey: [] - oauth2: - sessions:write 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: '201': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Event' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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`.' /sessions/{session_id}/runtimes: get: operationId: get_session_runtimes summary: List the runtimes a session's tasks ran on tags: - sessions security: - apiKey: [] - bearerApiKey: [] - oauth2: - sessions:read parameters: - name: session_id in: path required: true schema: type: string format: uuid - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/RuntimeContainer' pagination: $ref: '#/components/schemas/Pagination' '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 `workspaces:read`. /sessions/{session_id}/tasks: get: operationId: gen_session_tasks summary: List session tasks tags: - sessions security: - apiKey: [] - bearerApiKey: [] - oauth2: - sessions:read parameters: - name: session_id in: path required: true schema: type: string format: uuid - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Task' pagination: $ref: '#/components/schemas/Pagination' '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 `workspaces:read` and `agents:read` -- see the note on session events above about the `500` when `agents:read` is missing. /skills/{skill_id_or_name}: get: operationId: get_skill summary: Get a skill tags: - skills security: - apiKey: [] - bearerApiKey: [] - oauth2: - skills:read 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/SkillDetail' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-guild-response-model: SkillDetail description: Requires `skills:read`. /skills/{skill_id_or_name}/versions: post: operationId: create_skill_version summary: Create a skill version tags: - skills security: - apiKey: [] - bearerApiKey: [] - oauth2: - skills:write parameters: - name: skill_id_or_name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: properties: version_number: description: Semantic version, higher than the latest, e.g. 1.0.1 title: Version Number type: string description: description: What changed title: Description type: string body: description: The skill's content, in Markdown maxLength: 262144 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' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Requires `skills:write`. /triggers/{trigger_id}: get: operationId: get_trigger summary: Get a trigger tags: - triggers security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read parameters: - name: trigger_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceTrigger' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: operationId: update_trigger summary: Update a trigger tags: - triggers security: - oauth2: - workspaces:write parameters: - name: trigger_id in: path required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: description: Fields patchable on any trigger type. properties: name: default: null description: Trigger name title: Name nullable: true type: string event_type: default: null title: Event Type nullable: true type: string action: default: null title: Action nullable: true type: string service_config: default: null title: Service Config nullable: true additionalProperties: true type: object frequency: default: null description: How often to run nullable: true enum: - HOURLY - DAILY - WEEKLY - MONTHLY - CRON title: TimeTriggerFrequency type: string time_of_day: default: null description: HH:MM, for DAILY, WEEKLY and MONTHLY title: Time Of Day nullable: true type: string days_of_month: default: null title: Days Of Month nullable: true type: string days_of_week: default: null description: Comma-separated day names, e.g. MONDAY,THURSDAY, for WEEKLY title: Days Of Week nullable: true type: string minutes_of_hour: default: null title: Minutes Of Hour nullable: true type: string cron_expression: default: null description: Cron expression, for CRON title: Cron Expression nullable: true type: string cron_timezone: default: null title: Cron Timezone nullable: true type: string agent_input: default: null description: 'What the agent receives each run, e.g. {"type": "text", "text": "..."}' title: Agent Input nullable: true additionalProperties: true type: object title: UpdateTriggerBody type: object responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceTrigger' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /triggers/{trigger_id}/activate: post: operationId: activate_trigger summary: Activate a trigger tags: - triggers security: - oauth2: - workspaces:write parameters: - name: trigger_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceTrigger' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /triggers/{trigger_id}/deactivate: post: operationId: deactivate_trigger summary: Deactivate a trigger tags: - triggers security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:write parameters: - name: trigger_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceTrigger' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /triggers/{trigger_id}/run: post: operationId: run_trigger summary: Run a scheduled trigger now tags: - triggers security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:write parameters: - name: trigger_id in: path required: true schema: type: string format: uuid responses: '202': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceTrigger' links: TriggerSessions: operationId: get_trigger_sessions parameters: trigger_id: $request.path.trigger_id description: The run starts a session in the background; it appears among the trigger's sessions. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /triggers/{trigger_id}/sessions: get: operationId: get_trigger_sessions summary: List the sessions a trigger started tags: - triggers security: - apiKey: [] - bearerApiKey: [] - oauth2: - sessions:read parameters: - name: trigger_id in: path required: true schema: type: string format: uuid - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Session' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /users/{user_id_or_name}: get: operationId: get_user summary: Get a user tags: - accounts security: - oauth2: - organizations:read parameters: - name: user_id_or_name in: path required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/User' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /users/{user_id_or_name}/organizations: get: operationId: get_user_organizations summary: List a user's organization memberships tags: - accounts security: - oauth2: - organizations:read parameters: - name: user_id_or_name in: path required: true schema: type: string - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/OrganizationMembership' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}: get: operationId: get_agent_version summary: Get an agent version tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/AgentVersion' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/code: get: operationId: get_version_code summary: Get an agent version's source files tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/jobs: get: operationId: list_jobs summary: List all jobs for an agent version tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Job' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/publish: post: operationId: publish_agent_version summary: Publish an agent version tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:write 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/AgentVersionWithJob' links: PublishJob: operationId: get_publish_job parameters: version_id: $request.path.version_id description: Poll the publish job until its status is final. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Requires `agents:write`. /versions/{version_id}/publish/job: get: operationId: get_publish_job summary: Get latest publish job for an agent version tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Job' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/publish/steps: get: operationId: list_publish_steps summary: List publish steps for an agent version tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/JobStep' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/publish_pre_checks: post: operationId: create_publish_pre_checks summary: Run the checks a version must pass before publishing tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:write parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/JobStep' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/tool-access: get: operationId: get_agent_version_tool_access summary: Classify each of a version's tools as read or write description: Integration tools resolve to "read" or "write" from their underlying operation's HTTP method (or MCP hint); built-in and custom tools are reported as "unknown". tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/tools: get: operationId: get_agent_version_tools summary: 'List a version''s resolved tools: integration, sub-agent or service' description: Empty for versions built before tools were resolved. tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read parameters: - name: version_id in: path required: true schema: type: string format: uuid - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/AgentVersionTool' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/unpublish: post: operationId: unpublish_agent_version summary: Unpublish an agent version tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:write parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/AgentVersion' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/validation/job: get: operationId: get_validation_job summary: Get latest validation job for an agent version description: Returns either VALIDATION or PUBLISH jobs (publish jobs include validation). tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Job' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /versions/{version_id}/validation/steps: get: operationId: list_validation_steps summary: List validation steps for an agent version description: Returns steps from either VALIDATION or PUBLISH jobs. tags: - agents security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read parameters: - name: version_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/JobStep' '401': description: Unauthorized 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}: delete: operationId: delete_workspace_agent summary: Uninstall an agent from a workspace tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:write parameters: - name: workspace_agent_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object '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' get: operationId: get_workspace_agent summary: Get an installed agent tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read parameters: - name: workspace_agent_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceAgent' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: operationId: update_workspace_agent summary: Update an installed agent's version or settings tags: - workspaces security: - oauth2: - workspaces:write parameters: - name: workspace_agent_id in: path required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: properties: should_autoupdate: default: null description: Move to each new published version automatically title: Should Autoupdate nullable: true type: boolean is_default_chat_agent: default: null title: Is Default Chat Agent nullable: true type: boolean new_version_id: default: null description: Agent version to run, one of the agent's published versions title: New Version Id nullable: true format: uuid type: string required_credentials_mode: default: null nullable: true description: |- Whose credentials an agent may run with. ``SHARED`` admits only org-side credentials; ``MEMBER`` admits only the acting member's own, plus a credential dedicated to the agent, which is scoped to the agent under either mode. Unset means no requirement, and the resolution ladder decides on its own. enum: - SHARED - MEMBER title: RequiredCredentialsMode type: string title: UpdateWorkspaceAgentInput type: object responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceAgent' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request 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}/credential-associations: get: operationId: list_workspace_agent_credential_associations summary: List the credentials granted to an installed agent tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read parameters: - name: workspace_agent_id in: path required: true schema: type: string format: uuid - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/CredentialAssociation' pagination: $ref: '#/components/schemas/Pagination' '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 `workspaces:read`. Returns the credentials shared with the workspace agent, one row per association. post: operationId: create_workspace_agent_credential_association summary: Grant a credential to an installed agent tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - integrations:write 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 replace: default: false description: 'Revoke the bindings that would block this one, in the same transaction: either everything commits or nothing changes. A dedicated key and a grant serving every member exclude each other.' title: Replace type: boolean required: - auth_config_id - credentials_id title: CreateCredentialAssociationInput type: object 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' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Requires `integrations:write`. Creating credentials outside this dedicated mint stays human-only by design; the partner flow is admin-connects-once, key-attaches. /workspace_agents/{workspace_agent_id}/credential-associations/{association_id}: delete: operationId: delete_workspace_agent_credential_association summary: Revoke a credential from an installed agent tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - integrations:write 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' 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. /workspace_agents/{workspace_agent_id}/credentials/api-key: post: operationId: connect_workspace_agent_api_key summary: Create a dedicated API-key credential for a workspace agent description: |- The key is stored under the workspace owner's account and used only by this agent. Callable by a user or by an account API key with integrations write scope; a key can only connect credentials to agents it installed itself, under its own account. With ``replace``, every live grant on the agent for the integration that serves every member is revoked in the same transaction, whoever made it. Under per-member resolution a member's grant of their own credential serves only them, so it stays. tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - integrations:write 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: format: uuid title: Auth Config Id type: string - name: event_id in: query required: false schema: default: null title: Event Id nullable: true type: string - name: replace in: query required: false schema: default: false description: 'Revoke the bindings that would block this one, in the same transaction: either everything commits or nothing changes. A dedicated key and a grant serving every member exclude each other.' title: Replace type: boolean description: When `true`, revokes the existing bindings that would block this credential and creates the new one in the same transaction. Either everything commits or nothing changes, enabling atomic credential swaps. 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' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /workspace_agents/{workspace_agent_id}/upgrades: get: operationId: get_workspace_agent_upgrades summary: List an installed agent's version upgrades tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read parameters: - name: workspace_agent_id in: path required: true schema: type: string format: uuid - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/WorkspaceAgentUpgrade' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /workspaces: post: operationId: create_workspace summary: Create a workspace tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:write requestBody: required: true content: application/json: schema: properties: name: description: Workspace name title: Name type: string owner_id: description: Owning user or organization, by name or ID title: Owner Id type: string required: - name - owner_id title: CreateWorkspaceInput type: object responses: '201': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Workspace' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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`. /workspaces/{workspace_id_or_name}: get: operationId: get_workspace summary: Get a workspace and its compiled context tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read 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' description: Requires `workspaces:read`. A workspace with restricted membership (`should_restrict_members`) is invisible to every account key regardless of scope, and returns `404`. /workspaces/{workspace_id_or_name}/contexts: get: operationId: get_workspace_contexts summary: List a workspace's contexts tags: - workspaces security: - oauth2: - workspaces:read parameters: - name: workspace_id_or_name in: path required: true schema: type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Context' pagination: $ref: '#/components/schemas/Pagination' '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_context summary: Create a workspace context tags: - workspaces security: - oauth2: - workspaces:write parameters: - name: workspace_id_or_name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: properties: status: $ref: '#/components/schemas/ContextStatus' description: PUBLISHED to use it now, DRAFT to save it for review context: description: The instructions, in Markdown title: Context type: string summary: default: null description: What changed title: Summary nullable: true type: string required: - status - context title: CreateWorkspaceContextInput type: object responses: '201': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Context' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /workspaces/{workspace_id_or_name}/memberships: get: operationId: get_workspace_memberships summary: List a workspace's members tags: - workspaces security: - oauth2: - workspaces:read parameters: - name: workspace_id_or_name in: path required: true schema: type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/WorkspaceMembership' pagination: $ref: '#/components/schemas/Pagination' '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 tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - sessions:read parameters: - name: workspace_id_or_name in: path required: true schema: type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: trigger_id in: query required: false schema: default: null title: Trigger Id nullable: true format: uuid type: string - name: types in: query required: false schema: default: null title: Types nullable: true type: string - name: origin in: query required: false schema: default: null nullable: true description: Which Smith surface started the chat; unset outside Smith workspaces. enum: - CHAT - INSIGHTS title: SmithSessionOrigin type: string - name: workspace_agent_id in: query required: false schema: default: null title: Workspace Agent Id nullable: true format: uuid type: string - name: include_archived in: query required: false schema: default: false title: Include Archived type: boolean responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Session' pagination: $ref: '#/components/schemas/Pagination' '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 `workspaces:read`. post: operationId: create_workspace_session summary: Create a session in a workspace tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - sessions:write parameters: - name: workspace_id_or_name in: path required: true schema: type: string requestBody: required: false content: application/json: schema: type: object required: - session_type properties: session_type: type: string enum: - chat - agent_test description: '`chat` holds a conversation with `agent_id`, starting from `initial_prompt`. `agent_test` runs one agent version, given by `agent_version_id`.' agent_id: type: string description: 'For `chat`: the agent to converse with, by id or name.' initial_prompt: type: string description: 'For `chat`, required: the first message.' agent_version_id: type: string description: 'For `agent_test`, required: the agent version to run, draft or published.' context_override_id: type: string description: 'For `agent_test`: a context version to run with instead of the active one.' responses: '201': description: The created session content: application/json: schema: $ref: '#/components/schemas/Session' links: Session: operationId: gen_session parameters: session_id: $response.body#/id description: Read the session; its root task's status shows progress. SessionEvents: operationId: gen_session_events parameters: session_id: $response.body#/id description: Read the session's events as they arrive. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: 'Requires `sessions:write` on a workspace the key''s account owns. A key may create `chat` and `agent_test` sessions; `api_trigger` is a `403`. The key is recorded as the session''s `initiator` (serialized `type: "api_key"`), and a chat''s agent begins executing `initial_prompt` immediately.' /workspaces/{workspace_id_or_name}/triggers: get: operationId: get_triggers summary: List a workspace's triggers tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read parameters: - name: workspace_id_or_name in: path required: true schema: type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/WorkspaceTrigger' pagination: $ref: '#/components/schemas/Pagination' '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_trigger summary: Create a trigger in a workspace tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:write parameters: - name: workspace_id_or_name in: path required: true schema: type: string requestBody: required: false content: application/json: schema: discriminator: mapping: api: '#/components/schemas/CreateApiTriggerBody' time: '#/components/schemas/CreateTimeTriggerBody' webhook: '#/components/schemas/CreateWebhookTriggerBody' propertyName: type oneOf: - $ref: '#/components/schemas/CreateWebhookTriggerBody' - $ref: '#/components/schemas/CreateTimeTriggerBody' - $ref: '#/components/schemas/CreateApiTriggerBody' responses: '201': description: The created trigger content: application/json: schema: type: object '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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). /workspaces/{workspace_id_or_name}/workspace_agents: get: operationId: get_workspace_agents summary: List the agents installed in a workspace tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read parameters: - name: workspace_id_or_name in: path required: true schema: type: string - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - 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/WorkspaceAgent' pagination: $ref: '#/components/schemas/Pagination' '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 `workspaces:read` and `agents:read`. post: operationId: add_workspace_agent summary: Install an agent in a workspace tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:write parameters: - name: workspace_id_or_name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: properties: agent_id: description: 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: '201': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceAgent' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Requires `workspaces:write`, not `agents:write` -- the workspace-agent CREATE rule delegates to the workspace's own UPDATE privacy. /workspaces/{workspace_id_or_name}/workspace_skills: get: operationId: get_workspace_skills summary: List the skills attached to a workspace tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read - skills:read parameters: - name: workspace_id_or_name in: path required: true schema: type: string - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - 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/WorkspaceSkill' pagination: $ref: '#/components/schemas/Pagination' '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_skill summary: Attach a skill to a workspace tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:write - skills:read parameters: - name: workspace_id_or_name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: properties: skill_id: format: uuid title: Skill Id type: string required: - skill_id title: AddWorkspaceSkillInput type: object responses: '201': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceSkill' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /workspaces/{workspace_id_or_name}/workspace_skills/{workspace_skill_id}: delete: operationId: delete_workspace_skill summary: Detach a skill from a workspace tags: - workspaces security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:write - skills:read parameters: - name: workspace_id_or_name in: path required: true schema: type: string - name: workspace_skill_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object '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' components: schemas: Account: oneOf: - $ref: '#/components/schemas/Organization' - $ref: '#/components/schemas/User' AccountItem: description: |- An account as ``gen_serialize_account`` emits it. Users and organizations share the account pattern; ``email_domain`` appears only for organizations. properties: id: format: uuid title: Id type: string entity_type: title: Entity Type type: string created_at: format: date-time title: Created At type: string updated_at: format: date-time title: Updated At type: string type: enum: - user - organization title: Type type: string name: title: Name type: string full_name: title: Full Name nullable: true type: string avatar_url: title: Avatar Url nullable: true type: string bio: title: Bio nullable: true type: string banner_url: title: Banner Url nullable: true type: string website_url: title: Website Url nullable: true type: string github_url: title: Github Url nullable: true type: string x_url: title: X Url nullable: true type: string linkedin_url: title: Linkedin Url nullable: true type: string discord_url: title: Discord Url nullable: true type: string youtube_url: title: Youtube Url nullable: true type: string threads_url: title: Threads Url nullable: true type: string cached_likes_public_count: title: Cached Likes Public Count type: integer cached_forks_public_count: title: Cached Forks Public Count type: integer cached_installs_public_count: title: Cached Installs Public Count type: integer email_domain: default: null title: Email Domain nullable: true type: string required: - id - entity_type - created_at - updated_at - type - name - full_name - avatar_url - bio - banner_url - website_url - github_url - x_url - linkedin_url - discord_url - youtube_url - threads_url - cached_likes_public_count - cached_forks_public_count - cached_installs_public_count title: AccountItem type: object 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 - ADK description: type: string maxLength: 8192 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 - ADK 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.' creator_id: type: string format: uuid nullable: true description: The user, agent or API key that created this agent. Null for legacy rows created before creator attribution was recorded. 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 maxLength: 8192 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: {} creator: description: The user who created this agent. 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: {} last_updated_by: description: The user who pushed the newest version of this agent. 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 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 maxLength: 8192 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 llm_models: type: array items: {} nullable: true description: 'Acceptable provider/model pairs from guild.yaml `models`, tried in order. An entry naming a model asks for exactly it; an entry naming only a provider lets the server pick. NULL means the agent declared none and runs on the session default. E.g. [{"provider": "ANTHROPIC", "model": "claude-sonnet-5"}, {"provider": "OPENAI"}]' 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 maxLength: 8192 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 llm_models: type: array items: {} nullable: true description: 'Acceptable provider/model pairs from guild.yaml `models`, tried in order. An entry naming a model asks for exactly it; an entry naming only a provider lets the server pick. NULL means the agent declared none and runs on the session default. E.g. [{"provider": "ANTHROPIC", "model": "claude-sonnet-5"}, {"provider": "OPENAI"}]' 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: {} AgentVersionFile: properties: path: title: Path type: string content: title: Content type: string required: - path - content title: AgentVersionFile type: object AgentVersionTool: oneOf: - $ref: '#/components/schemas/AgentVersionToolAgent' - $ref: '#/components/schemas/AgentVersionToolIntegration' - $ref: '#/components/schemas/AgentVersionToolService' AgentVersionToolAgent: 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 description: The agent this tool calls. operations: type: array items: {} description: Tool names in the agent code that resolve to this unit. version_id: type: string format: uuid description: The agent version that declares this tool. version_range: type: string maxLength: 100 description: npm-style semver range the declaring code requests of the agent (e.g. ^1.2.3, ~1.2.3, 1.2.3, 1.x, *). agent_owner_name: {} agent_owner_type: {} agent_slug: {} type: {} AgentVersionToolIntegration: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time integration_id: type: string format: uuid description: The integration this tool's operations belong to. operations: type: array items: {} description: Tool names in the agent code that resolve to this unit. version_id: type: string format: uuid description: The agent version that declares this tool. version_range: type: string maxLength: 100 description: npm-style semver range the declaring code requests of the integration (e.g. ^1.2.3, ~1.2.3, 1.2.3, 1.x, *). integration_archived: {} integration_slug: {} type: {} AgentVersionToolService: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time kind: type: string enum: - BUILTIN - LEGACY - INTEGRATION description: Whether this name-only tool is a platform builtin, a legacy proxied service, or an unresolved third-party integration. name: type: string maxLength: 255 description: Service name (e.g. ui, console, github, zendesk). operations: type: array items: {} description: Tool names in the agent code that resolve to this unit. version_id: type: string format: uuid description: The agent version that declares this tool. type: {} AgentVersionType: enum: - EPHEMERAL - COMMITTED title: AgentVersionType type: string AgentVersionWithJob: allOf: - $ref: '#/components/schemas/AgentVersion' - type: object properties: job_id: type: string format: uuid nullable: true description: The validation or publish job this request started; null when it started none. required: - job_id ApiKey: description: |- An account API key as every key-returning endpoint serializes it. The one-time secret is shown only in the creation response and never appears in this shape. properties: id: format: uuid title: Id type: string entity_type: title: Entity Type type: string created_at: format: date-time title: Created At type: string updated_at: format: date-time title: Updated At type: string type: title: Type type: string enum: - account name: title: Name nullable: true type: string permissions: description: The key's scopes; write implies read. items: $ref: '#/components/schemas/ApiKeyScope' title: Permissions type: array owner: additionalProperties: true description: The account the key acts as (user or organization, item shape). title: Owner type: object created_by: additionalProperties: true description: The user who minted the key (item shape). title: Created By type: object required: - id - entity_type - created_at - updated_at - type - name - permissions - owner - created_by title: ApiKey type: object ApiKeyScope: properties: group: $ref: '#/components/schemas/ApiKeyScopeGroup' access: $ref: '#/components/schemas/ApiKeyScopeAccess' required: - group - access title: ApiKeyScope type: object ApiKeyScopeAccess: enum: - read - write title: ApiKeyScopeAccess type: string ApiKeyScopeGroup: enum: - agents - sessions - workspaces - skills - integrations - tool_call - applications - organizations title: ApiKeyScopeGroup type: string ConfigureLlmIntegrationToolsInput: properties: integration: title: Integration type: string tools: items: type: string title: Tools type: array required: - integration - tools title: ConfigureLlmIntegrationToolsInput type: object Context: oneOf: - $ref: '#/components/schemas/ContextAgentGenerated' - $ref: '#/components/schemas/ContextSystemGenerated' - $ref: '#/components/schemas/ContextUserGenerated' ContextAgentGenerated: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time generated_context: type: string maxLength: 262144 description: |- A blob of text, akin to a workspace.md file, that can be passed to an LLM to provide context on this workspace. This portion of the context is only editable by Guild systems. manual_context: type: string maxLength: 262144 description: |- A blob of text, akin to a workspace.md file, that can be passed to an LLM to provide context on this workspace. This portion of the context is editable by users and agents. status: type: string enum: - DRAFT - PUBLISHED task_id: type: string format: uuid description: |- This field references the guild task that was used to create this context. workspace_id: type: string format: uuid published_by_id: type: string format: uuid nullable: true description: |- If this context is published, this field references the user who published it, if applicable. If the context is still in draft, this field is null. summary: type: string maxLength: 255 nullable: true description: A short summary of the changes in this context version. task: {} type: {} ContextStatus: enum: - DRAFT - PUBLISHED title: ContextStatus type: string ContextSystemGenerated: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time generated_context: type: string maxLength: 262144 description: |- A blob of text, akin to a workspace.md file, that can be passed to an LLM to provide context on this workspace. This portion of the context is only editable by Guild systems. manual_context: type: string maxLength: 262144 description: |- A blob of text, akin to a workspace.md file, that can be passed to an LLM to provide context on this workspace. This portion of the context is editable by users and agents. status: type: string enum: - DRAFT - PUBLISHED workspace_id: type: string format: uuid published_by_id: type: string format: uuid nullable: true description: |- If this context is published, this field references the user who published it, if applicable. If the context is still in draft, this field is null. summary: type: string maxLength: 255 nullable: true description: A short summary of the changes in this context version. user_id: type: string format: uuid nullable: true description: |- If applicable, the user that was involved in generating this context (e.g. the user who added a new set of credentials). type: {} user: {} ContextUserGenerated: 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: This field references the user who created this context. generated_context: type: string maxLength: 262144 description: |- A blob of text, akin to a workspace.md file, that can be passed to an LLM to provide context on this workspace. This portion of the context is only editable by Guild systems. manual_context: type: string maxLength: 262144 description: |- A blob of text, akin to a workspace.md file, that can be passed to an LLM to provide context on this workspace. This portion of the context is editable by users and agents. status: type: string enum: - DRAFT - PUBLISHED workspace_id: type: string format: uuid published_by_id: type: string format: uuid nullable: true description: |- If this context is published, this field references the user who published it, if applicable. If the context is still in draft, this field is null. summary: type: string maxLength: 255 nullable: true description: A short summary of the changes in this context version. author: {} type: {} CreateApiTriggerBody: properties: workspace_agent_id: description: Installed agent ID format: uuid title: Workspace Agent Id type: string name: default: null description: Trigger name title: Name nullable: true type: string type: title: Type type: string enum: - api required: - workspace_agent_id - type title: CreateApiTriggerBody type: object 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: description: The message text title: Content type: string mode: default: text title: Mode type: string enum: - text required: - content title: CreateTextSessionEventInput type: object CreateTimeTriggerBody: properties: workspace_agent_id: description: Installed agent ID format: uuid title: Workspace Agent Id type: string name: default: null description: Trigger name title: Name nullable: true type: string type: title: Type type: string enum: - time frequency: $ref: '#/components/schemas/TimeTriggerFrequency' description: How often to run agent_input: additionalProperties: true description: 'What the agent receives each run, e.g. {"type": "text", "text": "..."}' title: Agent Input type: object time_of_day: default: null description: HH:MM, for DAILY, WEEKLY and MONTHLY title: Time Of Day nullable: true type: string days_of_month: default: null description: Comma-separated days of the month, -1 is the last day, for MONTHLY title: Days Of Month nullable: true type: string days_of_week: default: null description: Comma-separated day names, e.g. MONDAY,THURSDAY, for WEEKLY title: Days Of Week nullable: true type: string minutes_of_hour: default: null description: Comma-separated minutes, e.g. 0,30, for HOURLY title: Minutes Of Hour nullable: true type: string cron_expression: default: null description: Cron expression, for CRON title: Cron Expression nullable: true type: string cron_timezone: default: null description: IANA time zone for CRON, e.g. America/Los_Angeles title: Cron Timezone nullable: true type: string required: - workspace_agent_id - type - frequency - agent_input title: CreateTimeTriggerBody type: object CreateWebhookTriggerBody: properties: workspace_agent_id: description: Installed agent ID format: uuid title: Workspace Agent Id type: string name: default: null description: Trigger name title: Name nullable: true type: string type: title: Type type: string enum: - webhook webhook_config_id: format: uuid title: Webhook Config Id type: string event_type: default: null title: Event Type nullable: true type: string action: default: null title: Action nullable: true type: string service_config: default: null title: Service Config nullable: true additionalProperties: true type: object agent_input: default: null title: Agent Input nullable: true additionalProperties: true type: object required: - workspace_agent_id - type - webhook_config_id title: CreateWebhookTriggerBody type: object 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: {} runs_as: {} workspace: {} workspace_agent_id: {} CredentialResult: properties: status: default: issued title: Status type: string enum: - issued tunnel_id: format: uuid title: Tunnel Id type: string connector_token: title: Connector Token type: string expires_at: format: date-time title: Expires At type: string gateway_url: title: Gateway Url type: string required: - tunnel_id - connector_token - expires_at - gateway_url title: CredentialResult type: object 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 maxLength: 65536 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 - DEEPSEEK - ALIBABA - MOONSHOT - ZAI payload: type: object task_id: type: string format: uuid llm_model: type: string maxLength: 100 nullable: true inference_provider: {} model: {} model_publisher: {} 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 maxLength: 1024 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 maxLength: 65536 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: {} IntegrationCredentials: 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 these credentials are for creator_id: type: string format: uuid description: 'Who added these credentials: a user, or an account API key' owner_id: type: string format: uuid description: The account that owns these credentials extra_data: type: object nullable: true description: Non-secret installation metadata the provider returned at connect time params: type: object nullable: true description: The params in EntIntegrationParams user needs to provide during credentials linking target_id: type: string format: uuid nullable: true description: 'Availability target. NULL means a plain account-pool credential. A workspace target homes the credential to that workspace: it serves agents there whose bindings did not resolve, and never appears in a sibling workspace''s pool. An organization membership target binds the credential to that member in that organization. Ownership is always `owner`, never the target.' webhook_owner_identifier: type: string maxLength: 255 nullable: true config_params: {} creator: {} has_active_webhook_triggers: {} integration: {} policy_resources: {} signature_type: {} target: {} webhook_enabled: {} webhook_url: {} Invitation: 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 invitation. invitee_id: type: string format: uuid description: The user who is being invited to the organization. organization_id: type: string format: uuid description: The organization the invitee is being invited to. role: type: string enum: - ADMIN - MEMBER description: The role the invitee would have in the organization. status: type: string enum: - PENDING - CANCELED - DECLINED - ACCEPTED - EXPIRED description: The current status of the invitation. invitee: {} type: {} InvitationOrganization: oneOf: - $ref: '#/components/schemas/Invitation' - $ref: '#/components/schemas/InvitationOrganizationEmail' InvitationOrganizationEmail: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time code: type: string format: uuid description: The code that can be consumed to redeem the invitation. creator_id: type: string format: uuid description: The user who created this invitation. email: type: string format: email organization_id: type: string format: uuid description: The organization the invitee is being invited to. role: type: string enum: - ADMIN - MEMBER description: The role the invitee would have in the organization. status: type: string enum: - PENDING - CANCELED - DECLINED - ACCEPTED - EXPIRED description: The current status of the invitation. delivery_id: type: string maxLength: 255 nullable: true description: A unique identifier returned by the email provider that idenfies the email uniquely in their system. invitee_id: type: string format: uuid nullable: true description: The user who accepted the invitation, once available. message: type: string maxLength: 8192 nullable: true description: An optional message from the inviter that will be sent along the invitation. invitee: {} type: {} Job: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time job_type: type: string enum: - VALIDATION - PUBLISH - PUBLISH_PRE_CHECK target_id: type: string format: uuid status: type: string enum: - PENDING - RUNNING - SUCCEEDED - FAILED - ERRORED - CANCELLED completed_at: type: string format: date-time nullable: true error_message: type: string maxLength: 65536 nullable: true started_at: type: string format: date-time nullable: true target: {} JobStep: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time job_id: type: string format: uuid name: type: string maxLength: 100 description: Step name (e.g., tsc, babel, dependencies) status: type: string enum: - PENDING - RUNNING - SUCCEEDED - FAILED - SKIPPED - ERRORED completed_at: type: string format: date-time nullable: true content: type: string nullable: true index: type: integer nullable: true description: The index of the step in the execution. started_at: type: string format: date-time nullable: true job: {} OauthIdentity: description: |- Who an OAuth access token acts as: the consenting user, the client that holds the token, and the scopes the user granted. properties: type: title: Type type: string enum: - oauth user: additionalProperties: true description: The consenting user (item shape). title: User type: object client: additionalProperties: true description: The OAuth client holding the token. title: Client type: object scopes: description: The granted scopes. items: $ref: '#/components/schemas/ApiKeyScope' title: Scopes type: array required: - type - user - client - scopes title: OauthIdentity type: object 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 maxLength: 255 nullable: true closure_requested_at: type: string format: date-time nullable: true description: Set when an admin asks support to close the account, so a repeated request does not email support again. closure_requested_by_id: type: string format: uuid 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" OrganizationMembership: 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 this membership is publicly visible. organization_id: type: string format: uuid description: The organization this membership belongs to. role: type: string enum: - ADMIN - MEMBER description: The role of the user in the organization. user_id: type: string format: uuid description: The user who is a member of this organization. organization: $ref: '#/components/schemas/Organization' user: {} Pagination: type: object properties: total_count: description: Items matching the request across all pages. type: integer limit: description: Page size of this response. type: integer offset: description: Items skipped before this page. type: integer has_more: description: Whether another page follows; request it with offset + limit. type: boolean PaginationInfo: properties: total_count: description: Items matching the request across all pages. title: Total Count type: integer limit: description: Page size of this response. title: Limit type: integer offset: description: Items skipped before this page. title: Offset type: integer has_more: description: Whether another page follows; request it with offset + limit. title: Has More type: boolean required: - total_count - limit - offset - has_more title: PaginationInfo type: object PublicMe: anyOf: - $ref: '#/components/schemas/ApiKey' - $ref: '#/components/schemas/OauthIdentity' description: |- ``/v1/me`` answers for whichever credential called it; ``type`` tells the two apart. title: PublicMe 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. runtime_environment_id: type: string format: uuid nullable: true description: The environment this container was created from, when one was named. Null for containers booted from a bare image. container_id: {} created_by: {} destroyed_at: {} environment: {} image: {} started_at: {} status: {} workspace: {} Session: oneOf: - $ref: '#/components/schemas/SessionAgentTest' - $ref: '#/components/schemas/SessionChat' - $ref: '#/components/schemas/SessionGateway' - $ref: '#/components/schemas/SessionTriggerApi' - $ref: '#/components/schemas/SessionTriggerTime' - $ref: '#/components/schemas/SessionTriggerWebhook' SessionAgentTest: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time initiator_id: type: string format: uuid description: 'Who started this agent test session: a user, or an account API key testing from CI.' test_type: type: string enum: - MANUAL - EVAL description: Eval trials run as agent-test sessions; this separates them from sessions a person started from the agent editor. version_override_id: type: string format: uuid description: The specific agent version being tested in this session. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. context_override_id: type: string format: uuid nullable: true description: Optional context override for testing purposes. interrupted_at: type: string format: date-time nullable: true description: Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. seed_context: type: string maxLength: 262144 nullable: true description: Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. SessionChat: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time initiator_id: type: string format: uuid description: 'Who started this chat session: a user, or an account API key acting as its account.' workspace_id: type: string format: uuid description: The workspace this session belongs to. archived_at: type: string format: date-time nullable: true archived_by_id: type: string format: uuid nullable: true assistant_version_id: type: string format: uuid nullable: true description: The assistant version resolved for this chat session. Null for legacy sessions and direct agent sessions that did not use the assistant. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. name: type: string maxLength: 100 nullable: true description: The name/title of this chat session. Usually generated by an LLM based on the first prompt. origin: type: string enum: - CHAT - INSIGHTS nullable: true description: 'Set only on chats in a Smith workspace: CHAT for the Smith chat, INSIGHTS for a conversation the Ask Insights panel started. Chat lists filter on it to keep panel conversations out of the sidebar.' seed_context: type: string maxLength: 262144 nullable: true description: Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. SessionGateway: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time initiator_id: type: string format: uuid description: The member whose calls this session carries. A profile an admin declares is used by everyone in the workspace, so sessions are per member rather than per profile. ip_address: type: string maxLength: 45 description: The IP address of the client which initiated this session. last_active_at: type: string format: date-time description: 'When this session last carried a tool call. Written on every call: a session rolls over once it goes quiet, and nothing else touches the row, so updated_at would measure the session''s age instead of its idleness.' profile_id: type: string format: uuid description: The gateway profile this session's calls run as. Names the install directly, rather than leaving it to be inferred from the agent version, which several profiles share. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. seed_context: type: string maxLength: 262144 nullable: true description: Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. user_agent: type: string maxLength: 1024 nullable: true description: The User-Agent of the connecting client, naming the assistant driving this profile. Unset when the client sends no header. SessionTriggerApi: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time api_key_id: type: string format: uuid description: The API key which initiated this session. ip_address: type: string maxLength: 45 description: The IP address of the client which initiated this session. trigger_id: type: string format: uuid description: The trigger that initiated this session. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. seed_context: type: string maxLength: 262144 nullable: true description: Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. SessionTriggerTime: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time trigger_id: type: string format: uuid description: The trigger that initiated this session. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. seed_context: type: string maxLength: 262144 nullable: true description: Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. SessionTriggerWebhook: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time integration_webhook_id: type: string format: uuid description: The webhook that triggered this session. trigger_id: type: string format: uuid description: The webhook trigger that initiated this session. workspace_id: type: string format: uuid description: The workspace this session belongs to. context_id: type: string format: uuid nullable: true description: The context used in this session, if available. interrupted_at: type: string format: date-time nullable: true description: Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed. interrupted_by_id: type: string format: uuid nullable: true description: User who interrupted this session. remote_id: type: string maxLength: 255 nullable: true description: Remote identifier for correlating related events to this session. seed_context: type: string maxLength: 262144 nullable: true description: Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context. 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 creator_id: type: string format: uuid nullable: true description: The user or API key that created this skill. Null for legacy rows created before creator attribution was recorded. overview: type: string maxLength: 8192 nullable: true description: Optional human-facing overview for display and indexing. Falls back to the latest version description if not set. archived_by: {} creator: description: The user who created this skill. full_name: {} last_updated_by: description: The user who pushed the newest version of this skill. latest_version: {} likes_count: {} owner: {} type: {} viewer_can_edit: {} SkillDetail: description: |- A skill as ``gen_serialize_skill`` emits it. ``full_name``, ``likes_count`` and ``viewer_can_edit`` are computed at serialization time and exist on no entity. properties: id: format: uuid title: Id type: string entity_type: title: Entity Type type: string created_at: format: date-time title: Created At type: string updated_at: format: date-time title: Updated At type: string type: title: Type type: string enum: - skill full_name: title: Full Name type: string name: maxLength: 100 title: Name type: string overview: title: Overview nullable: true maxLength: 8192 type: string is_public: title: Is Public type: boolean avatar_url: title: Avatar Url nullable: true maxLength: 255 type: string archived_at: title: Archived At nullable: true format: date-time type: string owner: $ref: '#/components/schemas/AccountItem' likes_count: title: Likes Count type: integer viewer_can_edit: title: Viewer Can Edit type: boolean archived_by: nullable: true anyOf: - $ref: '#/components/schemas/AccountItem' - nullable: true enum: - null latest_version: nullable: true anyOf: - $ref: '#/components/schemas/SkillVersionItem' - nullable: true enum: - null required: - id - entity_type - created_at - updated_at - type - full_name - name - overview - is_public - avatar_url - archived_at - owner - likes_count - viewer_can_edit - archived_by - latest_version title: SkillDetail type: object 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 maxLength: 262144 description: Full markdown content for this skill version. description: type: string maxLength: 8192 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: 64 description: The semantic version number (MAJOR.MINOR.PATCH). author: {} skill: {} type: {} SkillVersionItem: description: A skill version as ``gen_serialize_skill_version`` emits it (ITEM). properties: id: format: uuid title: Id type: string entity_type: title: Entity Type type: string created_at: format: date-time title: Created At type: string updated_at: format: date-time title: Updated At type: string type: title: Type type: string enum: - skill_version version_number: title: Version Number type: integer description: title: Description nullable: true type: string required: - id - entity_type - created_at - updated_at - type - version_number - description title: SkillVersionItem type: object 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. This should be None if the task is not DONE or ERROR, or if the 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. This should be None if the task is not DONE or ERROR, or if the 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: enum: - HOURLY - DAILY - WEEKLY - MONTHLY - CRON title: TimeTriggerFrequency type: string 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 maxLength: 255 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. closure_requested_at: type: string format: date-time nullable: true description: Set when an admin asks support to close the account, so a repeated request does not email support again. closure_requested_by_id: type: string format: uuid nullable: true 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: {} 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. archived_at: type: string format: date-time nullable: true archived_by_id: type: string format: uuid nullable: true profile_name: type: string maxLength: 100 nullable: true description: Set when this install is an MCP gateway profile, addressed as /workspaces//mcp/. Unset on ordinary agent installs. 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' WorkspaceAgentUpgrade: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time new_version_id: type: string format: uuid old_version_id: type: string format: uuid workspace_agent_id: type: string format: uuid author_id: type: string format: uuid nullable: true description: If applicable, the person who upgraded the agent. Null means the agent was automatically upgraded. author: {} new_version: {} old_version: {} WorkspaceItem: description: A workspace as ``gen_serialize_workspace`` emits it. properties: id: format: uuid title: Id type: string entity_type: title: Entity Type type: string created_at: format: date-time title: Created At type: string updated_at: format: date-time title: Updated At type: string name: maxLength: 100 title: Name type: string full_name: title: Full Name type: string owner: $ref: '#/components/schemas/AccountItem' creator: description: 'Whoever created the workspace: a user, an account API key, or a trigger key (actor item shape).' title: Creator nullable: true additionalProperties: true type: object should_restrict_members: title: Should Restrict Members type: boolean unlimited_power_mode: title: Unlimited Power Mode type: boolean unlimited_power_mode_enabled: title: Unlimited Power Mode Enabled type: boolean restrict_account_credentials: title: Restrict Account Credentials type: boolean required_credentials_mode: title: Required Credentials Mode nullable: true type: string is_viewer_member: title: Is Viewer Member type: boolean archived_at: title: Archived At nullable: true format: date-time type: string archived_by: nullable: true anyOf: - $ref: '#/components/schemas/AccountItem' - nullable: true enum: - null required: - id - entity_type - created_at - updated_at - name - full_name - owner - creator - should_restrict_members - unlimited_power_mode - unlimited_power_mode_enabled - restrict_account_credentials - required_credentials_mode - is_viewer_member - archived_at - archived_by title: WorkspaceItem type: object WorkspaceList: description: The pagination envelope every collection endpoint returns. properties: items: items: $ref: '#/components/schemas/WorkspaceItem' title: Items type: array pagination: $ref: '#/components/schemas/PaginationInfo' required: - items - pagination title: WorkspaceList type: object WorkspaceMembership: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time added_by_id: type: string format: uuid description: The user who added this member. user_id: type: string format: uuid description: The user who is a member of this workspace. workspace_id: type: string format: uuid description: The workspace this membership belongs to. added_by: {} user: {} WorkspaceSkill: 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 skill to the workspace. skill_id: type: string format: uuid workspace_id: type: string format: uuid archived_at: type: string format: date-time nullable: true archived_by_id: type: string format: uuid nullable: true creator: {} skill: {} type: {} workspace: {} WorkspaceTrigger: oneOf: - $ref: '#/components/schemas/WorkspaceTriggerApi' - $ref: '#/components/schemas/WorkspaceTriggerTime' - $ref: '#/components/schemas/WorkspaceTriggerWebhook' WorkspaceTriggerApi: 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 description: The workspace agent to run when the trigger is activated. name: type: string maxLength: 255 description: Human-readable label identifying the trigger within its workspace. workspace_id: type: string format: uuid creator_id: type: string format: uuid nullable: true description: The actor (a user or an account API key) that created this trigger. Null for legacy rows created before creator attribution was recorded. deactivated_at: type: string format: date-time nullable: true description: If set, indicates when the trigger has been deactivated. type: type: string enum: - api description: Trigger type discriminator agent: $ref: '#/components/schemas/Agent' workspace_agent: $ref: '#/components/schemas/WorkspaceAgent' WorkspaceTriggerTime: 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 description: The workspace agent to run when the trigger is activated. agent_input: type: object description: |- The input that should be passed to the agent when the trigger is executed. It must match the input schema of the agent being triggerred. frequency: type: string enum: - HOURLY - DAILY - WEEKLY - MONTHLY - CRON name: type: string maxLength: 255 description: Human-readable label identifying the trigger within its workspace. next_run_at: type: string format: date-time description: When should the next run happen? workspace_id: type: string format: uuid creator_id: type: string format: uuid nullable: true description: The actor (a user or an account API key) that created this trigger. Null for legacy rows created before creator attribution was recorded. cron_expression: type: string maxLength: 100 nullable: true description: Standard 5-field cron expression. Only used with CRON frequency. cron_timezone: type: string maxLength: 50 nullable: true description: IANA timezone for cron evaluation (e.g. America/Los_Angeles). If omitted or None, cron evaluation uses UTC. days_of_month: type: array items: {} nullable: true description: 'None for non-MONTHLY frequency. List of days: [1, 8, 16].' days_of_week: type: array items: {} nullable: true description: 'None for non-WEEKLY frequency. List of days: ["MONDAY", "TUESDAY"].' deactivated_at: type: string format: date-time nullable: true description: If set, indicates when the trigger has been deactivated. minutes_of_hour: type: array items: {} nullable: true description: 'For HOURLY frequency only. Defaults to on the hour. List of minutes: [0, 15, 30, 45].' time_of_day: nullable: true description: None for `HOURLY` frequency. If not provided, will default to 9am. type: type: string enum: - time description: Trigger type discriminator agent: $ref: '#/components/schemas/Agent' workspace_aget: $ref: '#/components/schemas/WorkspaceAgent' WorkspaceTriggerWebhook: 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 description: The workspace agent to run when the trigger is activated. name: type: string maxLength: 255 description: Human-readable label identifying the trigger within its workspace. webhook_config_id: type: string format: uuid workspace_id: type: string format: uuid action: type: string maxLength: 100 nullable: true description: Optional action filter. If null, matches all actions. agent_input: type: object nullable: true creator_id: type: string format: uuid nullable: true description: The actor (a user or an account API key) that created this trigger. Null for legacy rows created before creator attribution was recorded. credentials_id: type: string format: uuid nullable: true deactivated_at: type: string format: date-time nullable: true description: If set, indicates when the trigger has been deactivated. event_type: type: string maxLength: 100 nullable: true description: |- The type of webhook event (e.g., 'pull_request', 'push'). If null, matches all events. service_config: type: object nullable: true integration: {} type: type: string enum: - webhook description: Trigger type discriminator agent: $ref: '#/components/schemas/Agent' workspace_aget: $ref: '#/components/schemas/WorkspaceAgent' _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 parameters: Limit: name: limit in: query required: false schema: default: 20 description: Maximum number of items to return. maximum: 500 minimum: 0 title: Limit type: integer Offset: name: offset in: query required: false schema: default: 0 description: Number of items to skip before returning results. maximum: 9223372036854775807 minimum: 0 title: Offset type: integer securitySchemes: apiKey: type: http scheme: basic description: 'API key: key id as the username, secret as the password. An account API key carries the same scopes as an OAuth token and is checked against the scopes listed under oauth2 on each operation. A trigger API key is limited to its trigger''s workspace and reaches only the session operations that list this scheme alongside the oauth2 scopes.' bearerApiKey: type: http scheme: bearer bearerFormat: : description: The same API key as one Bearer token, `:`. An account API key carries the same scopes as an OAuth token and is checked against the scopes listed under oauth2 on each operation. A trigger API key is limited to its trigger's workspace and reaches only the session operations that list this scheme alongside the oauth2 scopes. oauth2: type: oauth2 description: 'OAuth 2.0 authorization code flow with PKCE (S256). Discovery: https://api.guild.ai/.well-known/oauth-authorization-server.' flows: authorizationCode: authorizationUrl: https://api.guild.ai/v1/oauth/authorize tokenUrl: https://api.guild.ai/v1/oauth/token refreshUrl: https://api.guild.ai/v1/oauth/token scopes: agents:read: Read agents agents:write: Read and change agents sessions:read: Read sessions sessions:write: Read and change sessions workspaces:read: Read workspaces workspaces:write: Read and change workspaces skills:read: Read skills skills:write: Read and change skills integrations:read: Read integrations integrations:write: Read and change integrations applications:read: Read applications applications:write: Read and change applications organizations:read: Read organizations organizations:write: Read and change organizations connectorToken: type: http scheme: bearer description: 'Customer connector credential: the enrollment token to enroll, then the connector token it returns.'