> ## Documentation Index > Fetch the complete documentation index at: https://docs.guild.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1. > The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml). > Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer :`. See https://docs.guild.ai/api-reference/introduction#authentication. > To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers. > To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt. # Get a trigger ## OpenAPI ````yaml /api-reference/openapi.yaml get /triggers/{trigger_id} openapi: 3.0.3 info: title: Guild Public API version: 1.0.0 description: >- The Guild public API, served at https://api.guild.ai/v1. Authenticate with an account API key, sent as HTTP Basic (key id as the username, secret as the password) or as a Bearer token `:`, or with an OAuth 2.0 access token. Each operation lists the credentials it accepts and the scopes it needs; see https://docs.guild.ai/api-reference/introduction#scopes. Versions are path integers and v1 is the only one: a breaking change ships as a new version rather than changing v1. Lists page with `limit` and `offset` and report `pagination.has_more`. A session-events websocket also exists at wss://api.guild.ai/v1/sessions/{session_id}/events/ws with the same credentials on the handshake; OpenAPI cannot describe websockets, so it is not listed in paths. servers: - url: https://api.guild.ai/v1 description: Production security: [] tags: - name: accounts - name: agents - name: integrations - name: other - name: sessions - name: skills - name: triggers - name: workspaces paths: /triggers/{trigger_id}: get: tags: - triggers summary: Get a trigger operationId: get_trigger 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' security: - apiKey: [] - bearerApiKey: [] - oauth2: - workspaces:read components: schemas: WorkspaceTrigger: oneOf: - $ref: '#/components/schemas/WorkspaceTriggerApi' - $ref: '#/components/schemas/WorkspaceTriggerTime' - $ref: '#/components/schemas/WorkspaceTriggerWebhook' ErrorResponse: type: object properties: error: type: string message: type: string 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' 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 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' Account: oneOf: - $ref: '#/components/schemas/Organization' - $ref: '#/components/schemas/User' AgentVersion: oneOf: - $ref: '#/components/schemas/AgentVersionCommitted' - $ref: '#/components/schemas/AgentVersionEphemeral' 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: {} 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" 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: {} 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 ````