> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create cron trigger

> Creates a cron trigger that fires on a schedule. A trigger targeting an agent profile launches a new agent from the profile's current config on each firing; a trigger targeting an agent sends an input to that agent. Missed firings are coalesced, matching standard cron behavior: if one or more scheduled times pass while firing is delayed, the trigger fires once for the oldest missed time and then resumes its schedule from the current time, without retroactively firing for the other missed times.



## OpenAPI

````yaml /api-reference/openapi.yaml post /orgs/{orgID}/projects/{projectID}/cron-triggers
openapi: 3.1.2
info:
  title: Omnara API
  version: 0.1.0
  description: Public HTTP API contract for Omnara.
servers:
  - url: https://api.omnara.com/v1
    description: Hosted Omnara
security:
  - bearerAuth: []
  - browserSessionCookie: []
tags:
  - name: Agents
    description: >-
      Launch agents, send inputs, manage the input backlog, and work with tool
      calls.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/overview
  - name: Interactions
    description: List and resolve the approvals and questions that pause an agent.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/interactions
  - name: Actors
    description: Attribute agent inputs and interaction responses to external users.
    externalDocs:
      description: Guide
      url: >-
        https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution
  - name: Events
    description: Read or stream the agent timeline, list turns, and download artifacts.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/streaming
  - name: Configs and Profiles
    description: >-
      Create agent configs, manage reusable launch profiles, and set up
      integrations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/configuration
  - name: Models
    description: Configure model providers and models, and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/model-providers
  - name: Machines
    description: Register machines, control project access, and manage daemon tokens.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/connect
  - name: Machine Pools
    description: Define machine pools and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/pools
  - name: Secrets
    description: >-
      Manage secret ownership and versions, and inspect or grant project
      availability.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/secrets
  - name: Skills
    description: Manage versioned skill ownership and load skill instructions on demand.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/tools/skills
  - name: Organizations and Projects
    description: Create organizations and projects and manage membership.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/members
  - name: Users and API Keys
    description: >-
      The authenticated user, personal and organization API keys, and
      invitations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/api/authentication
  - name: Machine Daemon
    description: Routes the Omnara machine daemon uses to connect a machine.
paths:
  /orgs/{orgID}/projects/{projectID}/cron-triggers:
    parameters:
      - name: orgID
        in: path
        required: true
        schema:
          type: string
          pattern: ^org_[a-z2-7]{26}$
      - name: projectID
        in: path
        required: true
        schema:
          type: string
          pattern: ^proj_[a-z2-7]{26}$
    post:
      tags:
        - Configs and Profiles
      summary: Create cron trigger
      description: >-
        Creates a cron trigger that fires on a schedule. A trigger targeting an
        agent profile launches a new agent from the profile's current config on
        each firing; a trigger targeting an agent sends an input to that agent.
        Missed firings are coalesced, matching standard cron behavior: if one or
        more scheduled times pass while firing is delayed, the trigger fires
        once for the oldest missed time and then resumes its schedule from the
        current time, without retroactively firing for the other missed times.
      operationId: createCronTrigger
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCronTriggerRequest'
      responses:
        '200':
          description: Existing cron trigger returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CronTrigger'
        '201':
          description: Cron trigger created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CronTrigger'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
        - browserSessionCookie: []
          csrfHeader: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 255
      description: Idempotency key for replay-safe mutating requests.
  schemas:
    CreateCronTriggerRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - target
        - cron
        - message_template
      properties:
        name:
          $ref: '#/components/schemas/ResourceName'
        target:
          $ref: '#/components/schemas/CronTriggerTarget'
        cron:
          $ref: '#/components/schemas/CronExpression'
        timezone:
          $ref: '#/components/schemas/CronTimezone'
        message_template:
          $ref: '#/components/schemas/CronMessageTemplate'
        enabled:
          type: boolean
          default: true
    CronTrigger:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - name
        - target
        - cron
        - timezone
        - message_template
        - enabled
        - last_fired_at
        - next_fire_at
        - failure_report
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/CronTriggerID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        name:
          $ref: '#/components/schemas/ResourceName'
        target:
          $ref: '#/components/schemas/CronTriggerTarget'
        cron:
          $ref: '#/components/schemas/CronExpression'
        timezone:
          $ref: '#/components/schemas/CronTimezone'
        message_template:
          $ref: '#/components/schemas/CronMessageTemplate'
        enabled:
          type: boolean
        last_fired_at:
          oneOf:
            - $ref: '#/components/schemas/Timestamp'
            - type: 'null'
          description: When the trigger last fired, or null if it has never fired.
        next_fire_at:
          oneOf:
            - $ref: '#/components/schemas/Timestamp'
            - type: 'null'
          description: Next scheduled firing, or null while the trigger is disabled.
        failure_report:
          oneOf:
            - $ref: '#/components/schemas/CronTriggerFailureReport'
            - type: 'null'
          description: >-
            Most recent failed firing, or null if no firing has failed since the
            last successful firing.
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    ResourceName:
      type: string
      minLength: 1
      maxLength: 64
      x-omnara-unicode-normalization: NFC
      description: >-
        Human-readable name. Spaces and punctuation are allowed; leading or
        trailing whitespace and invisible or control characters are not.
    CronTriggerTarget:
      oneOf:
        - $ref: '#/components/schemas/AgentCronTriggerTarget'
        - $ref: '#/components/schemas/AgentProfileCronTriggerTarget'
      discriminator:
        propertyName: type
        mapping:
          agent:
            $ref: '#/components/schemas/AgentCronTriggerTarget'
          profile:
            $ref: '#/components/schemas/AgentProfileCronTriggerTarget'
    CronExpression:
      type: string
      description: >-
        Standard five-field cron expression (minute, hour, day of month, month,
        day of week). `TZ=`/`CRON_TZ=` prefixes are rejected; set the `timezone`
        field instead.
      minLength: 9
      maxLength: 256
    CronTimezone:
      type: string
      description: IANA time zone the schedule is evaluated in.
      default: UTC
      maxLength: 64
    CronMessageTemplate:
      type: string
      description: >-
        Go text/template rendered on each firing to produce the message sent to
        the target. The template receives a `trigger` value with `name`,
        `fired_at`, and `last_fired_at` fields. Rendering is capped at 64 KiB of
        output and one second of wall-clock time, and `printf` width and
        precision specifiers are capped at 1024; a firing whose template fails
        to render is recorded in `failure_report` without sending a message.
      maxLength: 65536
    CronTriggerID:
      type: string
      pattern: ^cron_[a-z2-7]{26}$
    OrganizationID:
      type: string
      pattern: ^org_[a-z2-7]{26}$
    ProjectID:
      type: string
      pattern: ^proj_[a-z2-7]{26}$
    Timestamp:
      type: string
      format: date-time
    CronTriggerFailureReport:
      type: object
      additionalProperties: false
      required:
        - message
        - will_retry
        - failed_at
      properties:
        message:
          type: string
          description: Why the most recent failed firing did not deliver a message.
        will_retry:
          type: boolean
          description: Whether the firing will be retried after the claim lease expires.
        failed_at:
          $ref: '#/components/schemas/Timestamp'
    Error:
      type: object
      additionalProperties: false
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message. Do not match on it programmatically.
        code:
          type: string
          description: Stable error code for programmatic handling.
          enum:
            - invalid_request
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - gone
            - request_too_large
            - unsupported_media_type
            - unprocessable
            - rate_limited
            - internal_error
            - upstream_error
            - service_unavailable
            - idempotency_key_conflict
            - state_transition_conflict
            - managed_work_admission_denied
            - pending_work
            - not_wake_capable
            - daemon_runtime_unregistered
            - validation_failed
            - csrf_check_failed
            - authentication_unavailable
    ClientErrorCode:
      type: string
      description: >-
        Stable error code carried by 4XX statuses. Subset of the Error code enum
        whose statuses are client errors.
      enum:
        - invalid_request
        - validation_failed
        - unauthorized
        - forbidden
        - csrf_check_failed
        - not_found
        - conflict
        - idempotency_key_conflict
        - state_transition_conflict
        - pending_work
        - not_wake_capable
        - gone
        - daemon_runtime_unregistered
        - request_too_large
        - unsupported_media_type
        - unprocessable
        - rate_limited
    ServerErrorCode:
      type: string
      description: >-
        Stable error code carried by 5XX statuses. Subset of the Error code enum
        whose statuses are server errors.
      enum:
        - internal_error
        - upstream_error
        - service_unavailable
        - authentication_unavailable
    AgentCronTriggerTarget:
      type: object
      additionalProperties: false
      required:
        - type
        - agent_id
      properties:
        type:
          type: string
          enum:
            - agent
        agent_id:
          $ref: '#/components/schemas/AgentID'
    AgentProfileCronTriggerTarget:
      type: object
      additionalProperties: false
      required:
        - type
        - agent_profile_id
      properties:
        type:
          type: string
          enum:
            - profile
        agent_profile_id:
          $ref: '#/components/schemas/AgentProfileID'
    AgentID:
      type: string
      pattern: ^agt_[a-z2-7]{26}$
    AgentProfileID:
      type: string
      pattern: ^aprf_[a-z2-7]{26}$
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication is required or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated principal is not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found or is not visible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >-
        The request conflicts with current resource state or idempotency
        history.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The service dependency required to satisfy the request is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ClientError:
      description: >-
        Any other client error. The body carries the shared Error envelope
        restricted to client error codes; statuses with a dedicated response
        above are documented precisely.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
              - error
              - code
            properties:
              error:
                type: string
                description: >-
                  Human-readable error message. Do not match on it
                  programmatically.
              code:
                $ref: '#/components/schemas/ClientErrorCode'
    ServerError:
      description: >-
        Any other server error. The body carries the shared Error envelope
        restricted to server error codes.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
              - error
              - code
            properties:
              error:
                type: string
                description: >-
                  Human-readable error message. Do not match on it
                  programmatically.
              code:
                $ref: '#/components/schemas/ServerErrorCode'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Omnara personal or organization access token
      description: An opaque Omnara personal or organization bearer token.
    browserSessionCookie:
      type: apiKey
      in: cookie
      name: __Host-omnara_session
      description: >-
        Browser session cookie. HTTPS deployments use __Host-omnara_session;
        local HTTP development uses omnara_session.
    csrfHeader:
      type: apiKey
      in: header
      name: X-Omnara-Csrf
      description: >-
        CSRF token header required for browser-session mutations. The value must
        match the session's CSRF cookie.

````