> ## Documentation Index > Fetch the complete documentation index at: https://docs.aide.app/llms.txt > Use this file to discover all available pages before exploring further. # Get v1procedures 1 ## OpenAPI ````yaml /api-reference/openapi.json get /v1/procedures/{id} openapi: 3.1.0 info: title: Aide API version: '1' description: >- Aide's public API. The dashboard, personal access tokens and the MCP server all use these endpoints. **Authentication.** `Authorization: Bearer oat_…` (a teammate's access token) or `Authorization: Bearer aide_live_…` (a workspace API key, created by an owner or admin under Settings > Developers). Either is bound to one account; every resource is scoped to it, and another account's id answers 404. **API keys** act as the workspace, not as a teammate. Operations that list `apiKey` under security accept them; everything else (the session, `me`, members, teams, billing, conversations, saved views, notifications, helpdesk and widget settings, and API keys themselves) answers 403 `api_key_not_allowed`. A key with only the `read` scope gets 403 `insufficient_scope` on writes (every method but `GET`, except `POST /v1/knowledge/search`, which only reads). A revoked, expired or unknown key answers 401 `invalid_api_key`. Requests are rate limited per key. **Webhooks.** Each delivery is a `POST` of the event JSON with `Aide-Event-Id`, `Aide-Event-Type`, `Aide-Delivery-Attempt` and `Aide-Signature: t=,v1=`. `v1` is the HMAC-SHA256 of `${t}.${raw body}` keyed with the endpoint secret (`whsec_…`, the whole string). For 24 h after a rotation a second `v1`, signed with the previous secret, is included; accept the request if any `v1` matches and `t` is within 5 minutes. Answer 2xx within 10 s; anything else is retried with exponential backoff (8 attempts over about 4 h). An endpoint is disabled after 25 failed attempts in a row with no success for 24 h. Deduplicate on the event id. **Responses.** Successful bodies are wrapped as `{ data }`. Page-numbered lists add `metadata`: `total` (exact up to 10,000, then 10,000 with `totalIsCapped: true`), `totalIsCapped`, `perPage`, `currentPage`, `lastPage` and `hasMore`. `page` runs from 1 to 500, and a page that starts past the first 10,000 rows answers 422 `page_too_deep`. `GET /v1/conversations` also takes a `cursor` (not with `page`): its `metadata.nextCursor` pages on in the same sort without counting, and a cursor page has null `total`, `currentPage` and `lastPage`. Message threads page with `before` and `meta.nextCursor`. **Errors.** Every error is `{ error: { type, code, message, requestId, fields? } }`. Validation failures are 422 with one entry per field in `fields`. **Rate limits.** Throttled routes return `X-RateLimit-Limit` and `X-RateLimit-Remaining`; a 429 adds `Retry-After` and `X-RateLimit-Reset`. servers: - url: https://app-api.aide.app description: Aide API security: [] tags: - name: Account - name: Agent - name: AgentAnalytics - name: AgentEntryPoint - name: AgentInstruction - name: AgentLinks - name: AgentPanelEvent - name: AgentPanelSessions - name: AgentTestConversation - name: Analytics - name: ApiKey - name: Attachment - name: AuditEvent - name: Auth - name: Billing - name: ChannelActivity - name: ChannelConfiguration - name: ChannelSettings - name: CompanySuggestion - name: ConnectedApp - name: Connection - name: ContactSync - name: Conversation - name: ConversationAi - name: ConversationCustomerContext - name: ConversationDraft - name: ConversationMacro - name: ConversationOrder - name: CustomField - name: EmailCodes - name: EmailMailbox - name: EmailPreferences - name: EmailVerifications - name: GoogleSessions - name: HelpdeskSetting - name: Integration - name: IntegrationAiAgentRule - name: IntegrationSidebar - name: Invitation - name: KnowledgeCollection - name: KnowledgeDocument - name: KnowledgeEntity - name: KnowledgeSource - name: Macro - name: Me - name: Member - name: MessageFeedback - name: MessageSender - name: Notification - name: NotificationChannel - name: OauthAuthorization - name: OnboardingAnswerCheck - name: OnboardingBuild - name: OnboardingQuestionTag - name: OnboardingTopic - name: Order - name: OrderAction - name: Plan - name: PolicyQuestion - name: PosthogProjects - name: ProcedureDraft - name: ProcedurePublication - name: ProcedureTriggerCheck - name: ProcedureVersion - name: Product - name: ProductFeedback - name: ProductPairing - name: Proposal - name: RoutingRule - name: SavedView - name: Scenario - name: ScenarioBackfill - name: ScenarioEstimate - name: ScenarioPreview - name: Schedule - name: SenderClassification - name: SenderRule - name: SetupStatus - name: ShopifyStaffLinks - name: SiThread - name: SitePreview - name: SlaPolicy - name: Team - name: Topic - name: TopicSuggestion - name: WebhookEndpoint - name: Widgets paths: /v1/procedures/{id}: get: tags: - Scenario operationId: procedure.show parameters: - name: id in: path required: true schema: type: string responses: '200': description: OK headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Scenario' required: - data '401': $ref: '#/components/responses/Unauthenticated' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' default: $ref: '#/components/responses/Error' security: - accessToken: [] - apiKey: [] components: headers: X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer Retry-After: description: Seconds until the window resets. schema: type: integer X-RateLimit-Reset: description: When the window resets. schema: type: string format: date-time schemas: Scenario: type: object properties: object: type: string const: scenario name: type: string createdAt: type: - string - 'null' id: type: string status: type: string enum: - draft - live - live_with_draft - paused - paused_with_draft updatedAt: type: - string - 'null' isActive: type: boolean agentId: type: - string - 'null' priority: type: string enum: - high - low - medium draft: type: - object - 'null' properties: name: type: string priority: type: string enum: - high - low - medium actions: type: array items: type: object properties: value: type: - string - 'null' macro: type: - object - 'null' properties: name: type: string id: type: string required: - name - id type: type: string enum: - ADD_TAG - APPLY_MACRO - ASSIGN - AUTOMATION - CLOSE_TICKET - COLLECT_FIELD - GENERATIVE_REPLY - INTERNAL_COMMENT - KNOWLEDGE_SETS - PREGENERATE_REPLY - PROMPT_INSTRUCTION - REPLY - SUGGEST_MACRO - SUGGEST_REPLY - TAG_ORDER field: type: - object - 'null' properties: id: type: string label: type: string required: - id - label collect: type: - object - 'null' properties: required: type: boolean mode: type: string enum: - always_ask - ask_if_missing - extract required: - required - mode knowledgeSources: type: - array - 'null' items: type: object properties: name: type: - string - 'null' id: type: string required: - name - id required: - value - macro - type - field - collect - knowledgeSources examples: type: object properties: use: type: array items: type: string dontUse: type: array items: type: string required: - use - dontUse applyAlways: type: boolean delay: type: string enum: - '10' - '15' - '5' - none deviation: type: object properties: question: type: string enum: - leave - stay person: type: string enum: - handoff - stay otherProcedure: type: string enum: - stay - switch required: - question - person - otherProcedure finish: type: - object - 'null' properties: kind: type: string enum: - close - handoff - reply handoffAfterFields: type: array items: type: object properties: id: type: string label: type: string required: - id - label required: - kind - handoffAfterFields procedure: type: - object - 'null' properties: schema: type: number const: 1 steps: type: array items: anyOf: - type: object properties: id: type: string type: type: string const: condition branches: type: array items: type: object properties: id: type: string when: type: string steps: type: array items: type: object properties: content: type: array items: anyOf: - type: object properties: kind: type: string const: action action: type: string enum: - ADD_TAG - APPLY_MACRO - ASSIGN - INTERNAL_COMMENT - TAG_ORDER - UPDATE_ADDRESS type: type: string const: chip label: type: - string - 'null' missing: type: boolean value: type: string macro: type: string required: - kind - action - type - label - missing - type: object properties: kind: type: string const: collect type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean collect: type: object properties: required: type: boolean mode: type: string enum: - always_ask - ask_if_missing - extract required: - kind - type - field - label - missing - type: object properties: kind: type: string const: use type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean required: - kind - type - field - label - missing - type: object properties: source: type: string kind: type: string const: knowledge type: type: string const: chip label: type: - string - 'null' missing: type: boolean required: - source - kind - type - label - missing - type: object properties: text: type: string type: type: string const: text required: - text - type id: type: string type: type: string const: instruction required: - content - id - type required: - id - when - steps otherwise: type: - array - 'null' items: type: object properties: content: type: array items: anyOf: - type: object properties: kind: type: string const: action action: type: string enum: - ADD_TAG - APPLY_MACRO - ASSIGN - INTERNAL_COMMENT - TAG_ORDER - UPDATE_ADDRESS type: type: string const: chip label: type: - string - 'null' missing: type: boolean value: type: string macro: type: string required: - kind - action - type - label - missing - type: object properties: kind: type: string const: collect type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean collect: type: object properties: required: type: boolean mode: type: string enum: - always_ask - ask_if_missing - extract required: - kind - type - field - label - missing - type: object properties: kind: type: string const: use type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean required: - kind - type - field - label - missing - type: object properties: source: type: string kind: type: string const: knowledge type: type: string const: chip label: type: - string - 'null' missing: type: boolean required: - source - kind - type - label - missing - type: object properties: text: type: string type: type: string const: text required: - text - type id: type: string type: type: string const: instruction required: - content - id - type required: - id - type - branches - otherwise - type: object properties: content: type: array items: anyOf: - type: object properties: kind: type: string const: action action: type: string enum: - ADD_TAG - APPLY_MACRO - ASSIGN - INTERNAL_COMMENT - TAG_ORDER - UPDATE_ADDRESS type: type: string const: chip label: type: - string - 'null' missing: type: boolean value: type: string macro: type: string required: - kind - action - type - label - missing - type: object properties: kind: type: string const: collect type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean collect: type: object properties: required: type: boolean mode: type: string enum: - always_ask - ask_if_missing - extract required: - kind - type - field - label - missing - type: object properties: kind: type: string const: use type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean required: - kind - type - field - label - missing - type: object properties: source: type: string kind: type: string const: knowledge type: type: string const: chip label: type: - string - 'null' missing: type: boolean required: - source - kind - type - label - missing - type: object properties: text: type: string type: type: string const: text required: - text - type id: type: string type: type: string const: instruction required: - content - id - type required: - schema - steps triggerThreshold: type: number whenToUse: type: - string - 'null' conditions: type: array items: type: array items: type: object properties: value: type: - string - 'null' topic: type: - object - 'null' properties: name: type: string id: type: string emoji: type: - string - 'null' categoryId: type: string required: - name - id - emoji - categoryId type: type: string enum: - CONTACT_FIELD - CUSTOM - FIELD - INBOX - INTEGRATION - INTENT - INTENT_CONFIDENCE - IS_FIRST_MESSAGE - PRIORITY_INTENT - SHOPIFY - TICKET_FIELD - TICKET_STATUS - TICKET_TAG - TOP_INTENT - USER_FIELD operator: type: string enum: - IS - IS_NOT fieldKey: type: - string - 'null' customFieldName: type: - string - 'null' required: - value - topic - type - operator - fieldKey - customFieldName required: - name - priority - actions - examples - applyAlways - delay - deviation - finish - procedure - triggerThreshold - whenToUse - conditions actions: type: array items: type: object properties: value: type: - string - 'null' macro: type: - object - 'null' properties: name: type: string id: type: string required: - name - id type: type: string enum: - ADD_TAG - APPLY_MACRO - ASSIGN - AUTOMATION - CLOSE_TICKET - COLLECT_FIELD - GENERATIVE_REPLY - INTERNAL_COMMENT - KNOWLEDGE_SETS - PREGENERATE_REPLY - PROMPT_INSTRUCTION - REPLY - SUGGEST_MACRO - SUGGEST_REPLY - TAG_ORDER field: type: - object - 'null' properties: id: type: string label: type: string required: - id - label collect: type: - object - 'null' properties: required: type: boolean mode: type: string enum: - always_ask - ask_if_missing - extract required: - required - mode knowledgeSources: type: - array - 'null' items: type: object properties: name: type: - string - 'null' id: type: string required: - name - id required: - value - macro - type - field - collect - knowledgeSources examples: type: object properties: use: type: array items: type: string dontUse: type: array items: type: string required: - use - dontUse runCount: type: number publishedAt: type: - string - 'null' applyAlways: type: boolean delay: type: string enum: - '10' - '15' - '5' - none deviation: type: object properties: question: type: string enum: - leave - stay person: type: string enum: - handoff - stay otherProcedure: type: string enum: - stay - switch required: - question - person - otherProcedure finish: type: - object - 'null' properties: kind: type: string enum: - close - handoff - reply handoffAfterFields: type: array items: type: object properties: id: type: string label: type: string required: - id - label required: - kind - handoffAfterFields procedure: type: - object - 'null' properties: schema: type: number const: 1 steps: type: array items: anyOf: - type: object properties: id: type: string type: type: string const: condition branches: type: array items: type: object properties: id: type: string when: type: string steps: type: array items: type: object properties: content: type: array items: anyOf: - type: object properties: kind: type: string const: action action: type: string enum: - ADD_TAG - APPLY_MACRO - ASSIGN - INTERNAL_COMMENT - TAG_ORDER - UPDATE_ADDRESS type: type: string const: chip label: type: - string - 'null' missing: type: boolean value: type: string macro: type: string required: - kind - action - type - label - missing - type: object properties: kind: type: string const: collect type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean collect: type: object properties: required: type: boolean mode: type: string enum: - always_ask - ask_if_missing - extract required: - kind - type - field - label - missing - type: object properties: kind: type: string const: use type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean required: - kind - type - field - label - missing - type: object properties: source: type: string kind: type: string const: knowledge type: type: string const: chip label: type: - string - 'null' missing: type: boolean required: - source - kind - type - label - missing - type: object properties: text: type: string type: type: string const: text required: - text - type id: type: string type: type: string const: instruction required: - content - id - type required: - id - when - steps otherwise: type: - array - 'null' items: type: object properties: content: type: array items: anyOf: - type: object properties: kind: type: string const: action action: type: string enum: - ADD_TAG - APPLY_MACRO - ASSIGN - INTERNAL_COMMENT - TAG_ORDER - UPDATE_ADDRESS type: type: string const: chip label: type: - string - 'null' missing: type: boolean value: type: string macro: type: string required: - kind - action - type - label - missing - type: object properties: kind: type: string const: collect type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean collect: type: object properties: required: type: boolean mode: type: string enum: - always_ask - ask_if_missing - extract required: - kind - type - field - label - missing - type: object properties: kind: type: string const: use type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean required: - kind - type - field - label - missing - type: object properties: source: type: string kind: type: string const: knowledge type: type: string const: chip label: type: - string - 'null' missing: type: boolean required: - source - kind - type - label - missing - type: object properties: text: type: string type: type: string const: text required: - text - type id: type: string type: type: string const: instruction required: - content - id - type required: - id - type - branches - otherwise - type: object properties: content: type: array items: anyOf: - type: object properties: kind: type: string const: action action: type: string enum: - ADD_TAG - APPLY_MACRO - ASSIGN - INTERNAL_COMMENT - TAG_ORDER - UPDATE_ADDRESS type: type: string const: chip label: type: - string - 'null' missing: type: boolean value: type: string macro: type: string required: - kind - action - type - label - missing - type: object properties: kind: type: string const: collect type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean collect: type: object properties: required: type: boolean mode: type: string enum: - always_ask - ask_if_missing - extract required: - kind - type - field - label - missing - type: object properties: kind: type: string const: use type: type: string const: chip field: type: string label: type: - string - 'null' missing: type: boolean required: - kind - type - field - label - missing - type: object properties: source: type: string kind: type: string const: knowledge type: type: string const: chip label: type: - string - 'null' missing: type: boolean required: - source - kind - type - label - missing - type: object properties: text: type: string type: type: string const: text required: - text - type id: type: string type: type: string const: instruction required: - content - id - type required: - schema - steps triggerThreshold: type: number whenToUse: type: - string - 'null' conditions: type: array items: type: array items: type: object properties: value: type: - string - 'null' topic: type: - object - 'null' properties: name: type: string id: type: string emoji: type: - string - 'null' categoryId: type: string required: - name - id - emoji - categoryId type: type: string enum: - CONTACT_FIELD - CUSTOM - FIELD - INBOX - INTEGRATION - INTENT - INTENT_CONFIDENCE - IS_FIRST_MESSAGE - PRIORITY_INTENT - SHOPIFY - TICKET_FIELD - TICKET_STATUS - TICKET_TAG - TOP_INTENT - USER_FIELD operator: type: string enum: - IS - IS_NOT fieldKey: type: - string - 'null' customFieldName: type: - string - 'null' required: - value - topic - type - operator - fieldKey - customFieldName missingWhenToUse: type: boolean knowledgeConflicts: type: array items: type: object properties: agent: type: object properties: name: type: string id: type: string required: - name - id ignored: type: boolean outsideSourceIds: type: array items: type: string required: - agent - ignored - outsideSourceIds required: - object - name - createdAt - id - status - updatedAt - isActive - agentId - priority - draft - actions - examples - runCount - publishedAt - applyAlways - delay - deviation - finish - procedure - triggerThreshold - whenToUse - conditions - missingWhenToUse - knowledgeConflicts Error: type: object description: Every error response, whatever the status (app/exceptions/handler.ts). properties: error: type: object properties: type: type: string enum: - api_error - authentication_error - invalid_request_error - permission_error - rate_limit_error code: type: string description: Stable, machine-readable error code. message: type: string requestId: type: string fields: type: array description: Per-field problems, on validation errors. items: type: object properties: field: type: string code: type: string message: type: string required: - field - code - message required: - type - code - message - requestId required: - error responses: Unauthenticated: description: Missing or invalid credentials (`authentication_error`). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The credential may not do this (`permission_error`). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: No such resource for this credential (`not_found`). content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Rate limited (`too_many_requests`). headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' Error: description: Any other error, in the same envelope. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: accessToken: type: http scheme: bearer bearerFormat: oat_… description: An access token, bound to one account. apiKey: type: http scheme: bearer bearerFormat: aide_live_… description: >- A workspace API key. Acts as the workspace with the `read` and/or `write` scope; never as a teammate. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.