> ## 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.

# Create a trigger in a workspace

> 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).



## OpenAPI

````yaml /api-reference/openapi.yaml post /workspaces/{workspace_id_or_name}/triggers
openapi: 3.0.3
info:
  title: Guild Public API
  version: 1.0.0
  description: >-
    The Guild public API, served at https://api.guild.ai/v1 and authenticated
    with account API keys (HTTP Basic, key id as the username and the secret as
    the password). See https://docs.guild.ai/api-reference/introduction for
    scopes and behavior. A session-events websocket also exists at
    wss://api.guild.ai/v1/sessions/{session_id}/events/ws with the same Basic
    auth on the handshake; OpenAPI cannot describe websockets, so it is not
    listed in paths.
servers:
  - url: https://api.guild.ai/v1
    description: Production
security: []
tags:
  - name: accounts
  - name: agents
  - name: oauth
  - name: sessions
  - name: skills
  - name: workspaces
paths:
  /workspaces/{workspace_id_or_name}/triggers:
    post:
      tags:
        - workspaces
      summary: Create a trigger in a workspace
      description: >-
        Requires `workspaces:write` and `agents:read`. A key may create `time`
        (schedule) triggers only -- `webhook` and `api` triggers are a `403`.
        `workspace_agent_id` must name an agent installed in this workspace. The
        key is recorded as the trigger's creator. See [Schedule
        triggers](/platform/schedule-triggers).
      operationId: create_trigger
      parameters:
        - name: workspace_id_or_name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTimeTriggerBody'
      responses:
        '201':
          description: The created trigger
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - apiKey: []
components:
  schemas:
    CreateTimeTriggerBody:
      title: CreateTimeTriggerBody
      type: object
      required:
        - workspace_agent_id
        - type
        - frequency
        - agent_input
      properties:
        workspace_agent_id:
          type: string
          format: uuid
          description: The installed workspace agent the trigger runs.
        type:
          type: string
          enum:
            - time
        frequency:
          $ref: '#/components/schemas/TimeTriggerFrequency'
        agent_input:
          type: object
          additionalProperties: true
          description: The fixed input the agent receives each time the trigger fires.
        time_of_day:
          type: string
          nullable: true
          description: >-
            Time of day in ISO format, such as `09:00`. Used by `DAILY`,
            `WEEKLY`, and `MONTHLY`.
        days_of_week:
          type: string
          nullable: true
          description: >-
            Comma-separated day names, such as `monday,thursday`. Used by
            `WEEKLY`.
        days_of_month:
          type: string
          nullable: true
          description: >-
            Comma-separated days from `1` to `31`, or `-1` for the last day of
            the month. Used by `MONTHLY`.
        minutes_of_hour:
          type: string
          nullable: true
          description: Comma-separated minutes from `0` to `59`.
        cron_expression:
          type: string
          nullable: true
          description: >-
            A five-field cron expression, such as `0 9 * * 1-5`. Required for
            `CRON` and rejected for other frequencies.
        cron_timezone:
          type: string
          nullable: true
          description: >-
            An IANA timezone name for `cron_expression`, such as
            `America/Los_Angeles`. Valid only for `CRON`.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    TimeTriggerFrequency:
      title: TimeTriggerFrequency
      type: string
      enum:
        - HOURLY
        - DAILY
        - WEEKLY
        - MONTHLY
        - CRON
  securitySchemes:
    apiKey:
      type: http
      scheme: basic
      description: 'Account API key: key id as the username, secret as the password.'

````