---
title: "Create a routine"
method: POST
path: "/routines"
tags: ["Routines"]
---

# Create a routine

`POST /routines`

## Request

- Base URL: `https://elicit.com/api/v2`
- URL: `https://elicit.com/api/v2/routines`
- Auth: HTTP bearer

Creates an active routine attached to an existing Research Agent session. Create the session first with `POST /api/v2/sessions/agents`. You need edit access to that session, and its owner's plan must include routines.

The schedule is interpreted in `timeZone`. Weekly schedules require `dayOfWeek` (0 is Sunday through 6 is Saturday); daily schedules require it to be null.

## Request body

- CreateRoutine
  - `name` string, required
  - `instruction` string, required: Instruction sent to the attached Research Agent session on every run.
  - `sessionId` string, uuid, required: Existing Research Agent session to attach.
  - `schedule` object, required
    - `cadence` 'daily' | 'weekly', required
    - `dayOfWeek` integer, nullable, required
    - `runAtLocalTime` string, required
    - `timeZone` string, required
  - `ownerNotificationLevel` 'all_runs' | 'output_or_attention' | 'attention_only', required

## Response `201`

The newly created active routine.

- RoutineResponse
  - `routine` Routine, required: A recurring Research Agent instruction. Archival is represented by a non-null removedAt rather than a separate status value.
    - `id` string, uuid, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `name` string, required
    - `status` 'active' | 'paused', required
    - `pauseReason` union, required
      - 'scheduler_projection_failed' | 'task_owner_lost_access' | 'session_unavailable' | 'session_owner_ineligible' | 'owner_plan_ineligible' | 'invalid_configuration'
      - string
    - `removedAt` string, nullable, required
    - `removedReason` 'user' | 'session_removed' | 'session_deleted' | 'null', nullable, required
    - `sessionId` string, required
    - `instruction` string, required
    - `schedule` object, required
      - `cadence` 'daily' | 'weekly', required
      - `dayOfWeek` integer, nullable, required
      - `runAtLocalTime` string, required
      - `timeZone` string, required
    - `ownerNotificationLevel` 'all_runs' | 'output_or_attention' | 'attention_only', required

## Other responses

- `400`: A path ID, query parameter, body field, schedule, cursor, or filter/sort combination is invalid.
- `401`: Authentication failed. The API key is missing, invalid, revoked, or expired.
- `403`: API access or routines are unavailable, or your role does not allow this action.
- `404`: The routine or requested session does not exist or is not accessible to you.
- `409`: The routine state changed, does not allow this operation, its session cannot run agent work, or another immediate run is already pending. Check the error code before retrying.
- `429`: Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.
- `500`: An unexpected error occurred. Retry reads with backoff; before retrying a write, check whether it took effect. See Error Handling for retry guidance.

## Changes

- **2026-10-13** `27c80b9a3470`: 6 info
  - added the optional property `error/details` to the response with the `400` status
  - added the optional property `error/details` to the response with the `401` status
  - added the optional property `error/details` to the response with the `403` status
  - added the optional property `error/details` to the response with the `404` status
  - …2 more
- **2026-10-02** `f9a4c55b1cde`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elicit/apis/elicit-api/changes/routines/post.md)

---

[API](https://skmtc.dev/elicit/apis/elicit-api.md) - [All operations](https://skmtc.dev/elicit/apis/elicit-api/llms.txt) - [OpenAPI document](https://skmtc.dev/elicit/apis/elicit-api/revisions/78db836edb9c?raw)