Clarity Routines API
The routines API from Clarity — 7 operation(s) for routines.
The routines API from Clarity — 7 operation(s) for routines.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/onclarity-com:onclarity-com-routines-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Fast Routines API
version: 0.1.0
tags:
- name: Routines
paths:
/api/v1/routines:
get:
tags:
- Routines
summary: List Routines
description: List routines for the current project (newest first). Admin users also see admin-only ones.
operationId: list_routines_api_v1_routines_get
security:
- HTTPBearer: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
default: 0
title: Offset
- name: cursor
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Cursor
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RoutineResponse'
title: Response List Routines Api V1 Routines Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Routines
summary: Create Routine
description: Create a routine. An ``active`` routine with a schedule trigger gets an EventBridge schedule.
operationId: create_routine_api_v1_routines_post
security:
- HTTPBearer: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRoutineRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoutineResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/routines/{routine_id}:
get:
tags:
- Routines
summary: Get Routine
description: Get a routine by id.
operationId: get_routine_api_v1_routines__routine_id__get
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoutineResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Routines
summary: Update Routine
description: Edit a routine; re-syncs the EventBridge schedule to the new status/trigger.
operationId: update_routine_api_v1_routines__routine_id__patch
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRoutineRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoutineResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Routines
summary: Delete Routine
description: Delete a routine and its EventBridge schedule.
operationId: delete_routine_api_v1_routines__routine_id__delete
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/routines/{routine_id}/pause:
post:
tags:
- Routines
summary: Pause Routine
description: Pause a routine (status → paused; schedule disabled).
operationId: pause_routine_api_v1_routines__routine_id__pause_post
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoutineResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/routines/{routine_id}/resume:
post:
tags:
- Routines
summary: Resume Routine
description: Resume a routine (status → active; schedule enabled/created).
operationId: resume_routine_api_v1_routines__routine_id__resume_post
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoutineResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/routines/{routine_id}/run:
post:
tags:
- Routines
summary: Run Routine
description: '"Run now" — fire a run on demand. Invokes the execute Lambda asynchronously (same Lambda the
schedule fires), which creates the run and launches the session; returns ``202 Accepted`` without
waiting. The new run then appears in ``GET /runs``.'
operationId: run_routine_api_v1_routines__routine_id__run_post
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
responses:
'202':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/routines/{routine_id}/runs:
get:
tags:
- Routines
summary: List Routine Runs
description: Run history for a routine (newest first), with the total count for pagination.
operationId: list_routine_runs_api_v1_routines__routine_id__runs_get
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
- name: limit
in: query
required: false
schema:
type: integer
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
default: 0
title: Offset
- name: cursor
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Cursor
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoutineRunListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/routines/{routine_id}/runs/{run_id}:
get:
tags:
- Routines
summary: Get Routine Run
description: 'Run detail (status/timestamps/session_id). The transcript/live stream is read from the bound
managed-agents session via ``run.session_id`` (no routines-specific events/stream endpoint).'
operationId: get_routine_run_api_v1_routines__routine_id__runs__run_id__get
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
- name: run_id
in: path
required: true
schema:
type: integer
title: Run Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoutineRunResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
src__routines__constants__RunStatus:
type: string
enum:
- running
- success
- failed
- needs_input
title: RunStatus
description: 'Status of a single routine run.
Derived from the bound managed-agent session: agent terminal (``done``) → ``success``;
still awaiting input at end of budget (``waiting``) → ``needs_input``; provider/exception
→ ``failed``. Stored as ``text`` in the DB.'
RoutineRunResponse:
properties:
id:
type: integer
title: Id
description: Run id.
routine_id:
type: integer
title: Routine Id
description: Owning routine id.
session_id:
anyOf:
- type: integer
- type: 'null'
title: Session Id
description: Bound managed-agent session id, if started.
trigger_type:
$ref: '#/components/schemas/TriggerType'
description: How the run was triggered.
status:
$ref: '#/components/schemas/src__routines__constants__RunStatus'
description: Run status.
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: Failure detail, if any.
email_message_id:
anyOf:
- type: integer
- type: 'null'
title: Email Message Id
description: OutboundMessage id for email delivery.
slack_message_id:
anyOf:
- type: integer
- type: 'null'
title: Slack Message Id
description: OutboundMessage id for Slack delivery.
started_at:
type: string
format: date-time
title: Started At
description: When the run started.
finished_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Finished At
description: When the run finished, if terminal.
type: object
required:
- id
- routine_id
- trigger_type
- status
- started_at
title: RoutineRunResponse
description: 'A routine run as returned by the API.
No ``summary``/``output`` — the agent''s reply/transcript is fetched from the bound session''s
events (managed-agents ``GET …/sessions/{session_id}/events``) via ``session_id``.'
RoutineRunListResponse:
properties:
items:
items:
$ref: '#/components/schemas/RoutineRunResponse'
type: array
title: Items
description: Runs on this page (newest first).
total:
type: integer
title: Total
description: Total runs for the routine (across all pages).
type: object
required:
- items
- total
title: RoutineRunListResponse
description: A page of routine runs plus the total count (for pagination).
ScheduleTrigger:
properties:
type:
type: string
const: schedule
title: Type
description: 'Trigger type. v1: ''schedule'' only.'
default: schedule
mode:
type: string
enum:
- simple
- raw
title: Mode
description: Which cron editor produced the expression.
default: simple
cron:
type: string
title: Cron
description: 5-field cron expression.
examples:
- 0 9 * * MON
timezone:
type: string
title: Timezone
description: IANA timezone for the schedule.
examples:
- America/New_York
type: object
required:
- cron
- timezone
title: ScheduleTrigger
description: 'A schedule trigger fires the routine on a cron schedule (the only v1 trigger).
The prototype''s ``cron`` trigger maps onto this ``schedule`` type. ``mode`` records which editor
produced the cron string (the simple Day/Week/Month picker vs. a raw cron field).'
RoutineResponse:
properties:
id:
type: integer
title: Id
description: Routine id.
project_id:
type: integer
title: Project Id
description: Owning project id.
created_by:
type: integer
title: Created By
description: User id of the creator.
agent_id:
type: integer
title: Agent Id
description: Managed agent the routine runs.
name:
type: string
title: Name
description: Routine name.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Human description.
status:
$ref: '#/components/schemas/RoutineStatus'
description: Routine status.
admin_only:
type: boolean
title: Admin Only
description: Admin-API only when true; hidden from the user-facing API.
default: false
prompt:
type: string
title: Prompt
description: First user message of each run.
triggers:
items:
$ref: '#/components/schemas/ScheduleTrigger'
type: array
title: Triggers
description: Schedule triggers.
destinations:
$ref: '#/components/schemas/src__routines__schemas__destinations__Destinations'
description: Delivery targets.
schedule_arn:
anyOf:
- type: string
- type: 'null'
title: Schedule Arn
description: EventBridge schedule ARN, if scheduled.
created_at:
type: string
format: date-time
title: Created At
description: Creation timestamp.
updated_at:
type: string
format: date-time
title: Updated At
description: Last update timestamp.
last_run_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Run At
description: Start time of the most recent run.
recent_runs:
items:
$ref: '#/components/schemas/src__routines__constants__RunStatus'
type: array
title: Recent Runs
description: Recent run statuses (oldest→newest) for the list-card sparkline; list view only.
recent_run_details:
items:
$ref: '#/components/schemas/RecentRunDetail'
type: array
title: Recent Run Details
description: Dated recent run outcomes, oldest to newest; list view only.
success_rate:
anyOf:
- type: number
- type: 'null'
title: Success Rate
description: Percent of finished recent runs that succeeded (0–100); list view only.
type: object
required:
- id
- project_id
- created_by
- agent_id
- name
- status
- prompt
- created_at
- updated_at
title: RoutineResponse
description: Routine as returned by the API.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
src__routines__schemas__destinations__Destinations:
properties:
emails:
items:
type: string
type: array
title: Emails
description: Email recipients.
slack:
anyOf:
- $ref: '#/components/schemas/src__routines__schemas__destinations__SlackDestination'
- type: 'null'
description: Slack channel, if any.
attach_files:
type: boolean
title: Attach Files
description: Deliver any file the run produces (export, report, deck) as a real email attachment, keeping its download link in the body. Email only. Files over the size cap are sent as a link. Routines saved before this field existed read as true.
default: true
type: object
title: Destinations
description: Where a routine run's result is delivered. All fields optional — a draft may have none.
UpdateRoutineRequest:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: New name.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: New description.
agent_id:
anyOf:
- type: integer
- type: 'null'
title: Agent Id
description: New managed agent.
prompt:
anyOf:
- type: string
- type: 'null'
title: Prompt
description: New prompt.
triggers:
anyOf:
- items:
$ref: '#/components/schemas/ScheduleTrigger'
type: array
- type: 'null'
title: Triggers
description: New triggers.
destinations:
anyOf:
- $ref: '#/components/schemas/src__routines__schemas__destinations__Destinations'
- type: 'null'
description: New destinations.
status:
anyOf:
- $ref: '#/components/schemas/RoutineStatus'
- type: 'null'
description: New status.
type: object
title: UpdateRoutineRequest
description: Request body for editing a routine (all fields optional). Re-syncs the schedule.
RoutineStatus:
type: string
enum:
- draft
- active
- paused
title: RoutineStatus
description: 'Lifecycle status of a routine.
``draft`` — saved but not scheduled (no EventBridge schedule created).
``active`` — scheduled and firing.
``paused`` — schedule disabled, kept for later resume.
Stored as ``text`` in the DB (no PG enum), mirroring managed-agents ``SessionStatus``.'
CreateRoutineRequest:
properties:
name:
type: string
title: Name
description: Routine name (not unique).
examples:
- Weekly VoC digest
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Optional human description.
agent_id:
type: integer
title: Agent Id
description: Managed agent to run.
prompt:
type: string
title: Prompt
description: First user message sent on each run.
triggers:
items:
$ref: '#/components/schemas/ScheduleTrigger'
type: array
title: Triggers
description: 'v1: at most one schedule trigger.'
destinations:
$ref: '#/components/schemas/src__routines__schemas__destinations__Destinations'
description: Slack/email delivery targets.
status:
$ref: '#/components/schemas/RoutineStatus'
description: Initial status. 'draft' creates no schedule.
default: draft
type: object
required:
- name
- agent_id
- prompt
title: CreateRoutineRequest
description: Request body for creating a routine. No ``config`` — the agent is fully pre-configured.
src__routines__schemas__destinations__SlackDestination:
properties:
channel_id:
type: string
title: Channel Id
description: Slack channel id.
examples:
- C0VOCWEEK
channel_name:
type: string
title: Channel Name
description: Slack channel name (without '#').
examples:
- voc-weekly
type: object
required:
- channel_id
- channel_name
title: SlackDestination
description: A Slack channel a routine run is delivered to.
RecentRunDetail:
properties:
status:
$ref: '#/components/schemas/src__routines__constants__RunStatus'
started_at:
type: string
format: date-time
title: Started At
type: object
required:
- status
- started_at
title: RecentRunDetail
TriggerType:
type: string
enum:
- schedule
- manual
title: TriggerType
description: 'How a run was triggered.
``schedule`` — the routine''s cron fired (EventBridge schedule -> execute Lambda).
``manual`` — a user hit "Run now" in the UI (the same Lambda, invoked on demand, not by the cron).
Stored as ``text`` in the DB; ``api`` stays reserved for later without a migration.'
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
HTTPBasic:
type: http
scheme: basic