> ## Documentation Index > Fetch the complete documentation index at: https://docs.guild.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1. > The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml). > Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer :`. See https://docs.guild.ai/api-reference/introduction#authentication. > To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers. > To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt. # Create an agent version ## OpenAPI ````yaml /api-reference/openapi.yaml post /agents/{agent_id_or_name}/versions 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: /agents/{agent_id_or_name}/versions: post: tags: - agents summary: Create an agent version operationId: create_agent_version 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: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/AgentVersionWithJob' '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. '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - apiKey: [] - bearerApiKey: [] - oauth2: - agents:write components: schemas: AgentVersionType: enum: - EPHEMERAL - COMMITTED title: AgentVersionType type: string AgentVersionFile: properties: path: title: Path type: string content: title: Content type: string required: - path - content title: AgentVersionFile type: object 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 ErrorResponse: type: object properties: error: type: string message: type: string AgentVersion: oneOf: - $ref: '#/components/schemas/AgentVersionCommitted' - $ref: '#/components/schemas/AgentVersionEphemeral' AgentVersionCommitted: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time agent_id: type: string format: uuid author_id: type: string format: uuid validation_status: type: string enum: - SKIPPED - PENDING - RUNNING - PASSED - FAILED dependencies: type: object nullable: true description: npm package.json dependencies description: type: string 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 ````