Clarity Next Steps API
The next_steps API from Clarity — 2 operation(s) for next_steps.
The next_steps API from Clarity — 2 operation(s) for next_steps.
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-next-steps-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 Next Steps API
version: 0.1.0
tags:
- name: next_steps
paths:
/api/v1/next-steps:
get:
tags:
- next_steps
summary: List Next Steps
description: 'The caller''s own next steps in the project they are viewing.
Only the ``shown`` group, in state waiting or shown (or snoozed with the snooze over),
most important kind first, then newest; at most 3. Empty for staff, and when the project''s
``nextStepsEnabled`` flag is off.
Raises:
HTTPException: 401/403/404 from the shared token and project check.'
operationId: list_next_steps_api_v1_next_steps_get
security:
- HTTPBearer: []
parameters:
- name: surface
in: query
required: false
schema:
$ref: '#/components/schemas/Surface'
description: Where the cards will be shown
default: overview
description: Where the cards will be shown
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/NextStepListResponse'
'401':
description: Not authenticated
'404':
description: Not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/next-steps/{step_id}/events:
post:
tags:
- next_steps
summary: Post Next Step Event
description: 'Record what happened to one of the caller''s cards, and move the step accordingly.
``shown`` sets ``first_shown_at`` once; ``clicked`` sets ``clicked_at``; ``snoozed`` hides it
for 14 days; ``dismissed`` stops it; ``done`` closes it. Every accepted call appends an event.
Raises:
HTTPException: 404 when the step is not the caller''s (or not in this project, held back,
or unknown), for staff, and when the flag is off — never 403.
HTTPException: 422 for an unknown action or surface.
Example:
```json
{"action": "clicked", "surface": "overview"}
```'
operationId: post_next_step_event_api_v1_next_steps__step_id__events_post
security:
- HTTPBearer: []
parameters:
- name: step_id
in: path
required: true
schema:
type: integer
maximum: 9223372036854775807
minimum: 1
title: Step Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NextStepEventRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/NextStepEventResponse'
'401':
description: Not authenticated
'404':
description: Not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
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
NextStepEventResponse:
properties:
id:
type: integer
title: Id
state:
type: string
title: State
description: The step's state after the event
type: object
required:
- id
- state
title: NextStepEventResponse
NextStepResponse:
properties:
id:
type: integer
title: Id
kind:
type: string
title: Kind
description: 'Which rule found it: draft_routine, routine_only_you, routine_failed, repeated_question'
examples:
- routine_failed
title:
type: string
title: Title
examples:
- Your routine “Weekly churn” failed
detail:
type: string
title: Detail
examples:
- Its last run did not finish. Open it to see what went wrong and run it again.
action_label:
type: string
title: Action Label
description: The card's action button
examples:
- Open the routine
href:
anyOf:
- type: string
- type: 'null'
title: Href
description: 'Where the action goes: a path inside the project (prefix it with /project/{id}). Set for link steps; null for prompt steps.'
examples:
- /routines/12
prompt:
anyOf:
- type: string
- type: 'null'
title: Prompt
description: A prepared copilot prompt the action puts in the composer. Set for prompt steps; null otherwise.
state:
type: string
title: State
description: waiting, shown or snoozed (a snooze that is over)
created_at:
type: string
format: date-time
title: Created At
type: object
required:
- id
- kind
- title
- detail
- action_label
- state
- created_at
title: NextStepResponse
description: 'One card: the caller''s own step, in their own things'' words.'
NextStepEventRequest:
properties:
action:
type: string
enum:
- shown
- clicked
- dismissed
- snoozed
- done
title: Action
description: 'shown: the card was displayed; clicked: its action was taken; snoozed: ''Not now'' (back in 14 days); dismissed: never again; done: the person says it is done'
surface:
$ref: '#/components/schemas/Surface'
description: Where the card was shown
default: overview
type: object
required:
- action
title: NextStepEventRequest
description: Something that happened to a card in the caller's browser.
example:
action: shown
surface: overview
Surface:
type: string
enum:
- overview
title: Surface
description: Where a step is shown. v1 has one; the sync API's own events carry ``SYNC_SURFACE``.
NextStepListResponse:
properties:
steps:
items:
$ref: '#/components/schemas/NextStepResponse'
type: array
title: Steps
description: The caller's own steps, most important first, at most 3. Empty for staff and when the project's nextStepsEnabled flag is off.
type: object
required:
- steps
title: NextStepListResponse
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