Clarity Routines Admin API
The routines_admin API from Clarity — 8 operation(s) for routines_admin.
The routines_admin API from Clarity — 8 operation(s) for routines_admin.
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-admin-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 Admin API
version: 0.1.0
tags:
- name: routines_admin
paths:
/api/admin/v1/routines/execute:
post:
tags:
- routines_admin
summary: Execute Routine
description: 'Launch a run for a routine (invoked by the schedule''s Lambda, and by the user "Run now" path
which invokes this same Lambda asynchronously).
Only *launches* — opens the session and sends the prompt, then returns the ``running`` run without
waiting for the agent. ``RoutineReconciler`` finalizes the run later from the session status.'
operationId: execute_routine_api_admin_v1_routines_execute_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminExecuteRoutineRequest'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoutineRunResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/admin/v1/routines/runs/reconcile:
post:
tags:
- routines_admin
summary: Reconcile Runs
description: 'Finalize routine runs stuck in ``running`` whose session changed status outside the runner''s
watch (invoked by the reconciler Lambda ~every 5 min). Returns ``{reconciled: N}``.'
operationId: reconcile_runs_api_admin_v1_routines_runs_reconcile_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
security:
- HTTPBearer: []
/api/admin/v1/routines:
get:
tags:
- routines_admin
summary: List Routines
description: List a project's routines (newest first), including admin-only ones.
operationId: list_routines_api_admin_v1_routines_get
security:
- HTTPBearer: []
parameters:
- name: project_id
in: query
required: true
schema:
type: integer
title: Project 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:
type: array
items:
$ref: '#/components/schemas/RoutineResponse'
title: Response List Routines Api Admin V1 Routines Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- routines_admin
summary: Create Routine
description: Create a routine in a project. Defaults to ``admin_only=True`` (hidden from the user API).
operationId: create_routine_api_admin_v1_routines_post
security:
- HTTPBearer: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCreateRoutineRequest'
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/admin/v1/routines/{routine_id}:
get:
tags:
- routines_admin
summary: Get Routine
description: Get a routine by id within a project (admin-only routines included).
operationId: get_routine_api_admin_v1_routines__routine_id__get
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
- name: project_id
in: query
required: true
schema:
type: integer
title: Project 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_admin
summary: Update Routine
description: Edit a routine; re-syncs its EventBridge schedule. ``admin_only`` is fixed at create time.
operationId: update_routine_api_admin_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/AdminUpdateRoutineRequest'
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_admin
summary: Delete Routine
description: Delete a routine and its EventBridge schedule.
operationId: delete_routine_api_admin_v1_routines__routine_id__delete
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
- name: project_id
in: query
required: true
schema:
type: integer
title: Project Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/admin/v1/routines/{routine_id}/pause:
post:
tags:
- routines_admin
summary: Pause Routine
description: Pause a routine (status → paused; schedule disabled).
operationId: pause_routine_api_admin_v1_routines__routine_id__pause_post
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
- name: project_id
in: query
required: true
schema:
type: integer
title: Project 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/admin/v1/routines/{routine_id}/resume:
post:
tags:
- routines_admin
summary: Resume Routine
description: Resume a routine (status → active; schedule enabled/created).
operationId: resume_routine_api_admin_v1_routines__routine_id__resume_post
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
- name: project_id
in: query
required: true
schema:
type: integer
title: Project 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/admin/v1/routines/{routine_id}/runs:
get:
tags:
- routines_admin
summary: List Routine Runs
description: Run history for a routine (newest first), with the total count for pagination.
operationId: list_routine_runs_api_admin_v1_routines__routine_id__runs_get
security:
- HTTPBearer: []
parameters:
- name: routine_id
in: path
required: true
schema:
type: integer
title: Routine Id
- name: project_id
in: query
required: true
schema:
type: integer
title: Project 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/admin/v1/routines/{routine_id}/runs/{run_id}:
get:
tags:
- routines_admin
summary: Get Routine Run
description: Run detail (status/timestamps/session_id) within a project.
operationId: get_routine_run_api_admin_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
- name: project_id
in: query
required: true
schema:
type: integer
title: Project 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.
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``.'
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.
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.'
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
AdminExecuteRoutineRequest:
properties:
project_id:
type: integer
title: Project Id
description: Owning project id (the schedule's target project).
routine_id:
type: integer
title: Routine Id
description: Routine to run.
trigger_type:
$ref: '#/components/schemas/TriggerType'
description: 'How the run was triggered: ''schedule'' or ''manual''.'
default: schedule
type: object
required:
- project_id
- routine_id
title: AdminExecuteRoutineRequest
description: 'Body for the admin ``/execute`` endpoint, sent by the execute Lambda (no user token).
Just enough to identify the routine and its project; the routine (prompt, agent, destinations) is
loaded by id. ``trigger_type`` distinguishes a scheduled fire from a UI "Run now"; it defaults to
``schedule`` so the EventBridge target input (which omits it) keeps working unchanged.'
AdminCreateRoutineRequest:
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
project_id:
type: integer
title: Project Id
description: Owning project id.
created_by:
type: integer
title: Created By
description: User id to record as the creator.
admin_only:
type: boolean
title: Admin Only
description: Hide from the user-facing API (admin-only).
default: true
type: object
required:
- name
- agent_id
- prompt
- project_id
- created_by
title: AdminCreateRoutineRequest
description: 'Admin ``POST /routines`` body (no user token): the user create payload plus the admin-only
fields. ``project_id``/``created_by`` come from the body (the admin contour has no session);
``admin_only`` defaults to ``True`` (the admin API''s purpose), but a user-visible routine can be
created by setting it ``False``.'
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AdminUpdateRoutineRequest:
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.
project_id:
type: integer
title: Project Id
description: Owning project id (scopes the routine).
type: object
required:
- project_id
title: AdminUpdateRoutineRequest
description: 'Admin ``PATCH /routines/{id}`` body: the user update payload, scoped by ``project_id``
(``admin_only`` is fixed at create time).'
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
HTTPBasic:
type: http
scheme: basic