Amigo Context Graphs API
The Context Graphs API from Amigo — 4 operation(s) for context graphs.
OpenAPI Specification
openapi: 3.1.0
info:
title: Amigo Account Context Graphs API
version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
Bearer-Authorization-Organization: []
Basic: []
tags:
- name: Context Graphs
paths:
/v1/{workspace_id}/context-graphs:
post:
tags:
- Context Graphs
summary: Create a context graph
description: Create a new context graph in a workspace. Requires `ContextGraph.create` permission.
operationId: create-context_graph
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContextGraphRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContextGraphResponse'
'404':
description: Not found.
'409':
description: Name already taken.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Invalid request body.
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
get:
tags:
- Context Graphs
summary: List context graphs
description: List context graphs in a workspace with pagination. Requires `ContextGraph.view` permission.
operationId: list-context_graphs
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: search
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/SearchString'
- type: 'null'
title: Search
- name: sort_by
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Sort By
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
exclusiveMinimum: 0
default: 10
title: Limit
- name: continuation_token
in: query
required: false
schema:
type: integer
default: 0
title: Continuation Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResponse_ContextGraphResponse_'
'404':
description: Not found.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/context-graphs/{context_graph_id}:
get:
tags:
- Context Graphs
summary: Get a context graph
description: Retrieve a context graph by ID. Requires `ContextGraph.view` permission.
operationId: get-context_graph
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: context_graph_id
in: path
required: true
schema:
type: string
format: uuid
title: Context Graph Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContextGraphResponse'
'404':
description: Not found.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Context Graphs
summary: Update a context graph
description: Update a context graph's name or description. Requires `ContextGraph.update` permission.
operationId: update-context_graph
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: context_graph_id
in: path
required: true
schema:
type: string
format: uuid
title: Context Graph Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateContextGraphRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContextGraphResponse'
'404':
description: Not found.
'409':
description: Name already taken.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Invalid request body.
delete:
tags:
- Context Graphs
summary: Delete a context graph
description: Delete a context graph. context graph versions are retained. Requires `ContextGraph.delete` permission.
operationId: delete-context_graph
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: context_graph_id
in: path
required: true
schema:
type: string
format: uuid
title: Context Graph Id
responses:
'204':
description: Successful Response
'404':
description: Not found.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/context-graphs/{context_graph_id}/versions:
post:
tags:
- Context Graphs
summary: Create a context graph version
description: Create a new version of a context graph. Version number is auto-incremented. Requires `ContextGraph.create` permission for the first version and `ContextGraph.update` permission afterward.
operationId: create-context_graph-version
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: context_graph_id
in: path
required: true
schema:
type: string
format: uuid
title: Context Graph Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContextGraphVersionRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContextGraphVersionResponse'
'404':
description: Not found.
'409':
description: Name already taken.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Invalid request body.
get:
tags:
- Context Graphs
summary: List context graph versions
description: List versions of a context graph with pagination. Requires `ContextGraph.view` permission.
operationId: list-context_graph-versions
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: context_graph_id
in: path
required: true
schema:
type: string
format: uuid
title: Context Graph Id
- name: sort_by
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Sort By
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
exclusiveMinimum: 0
default: 10
title: Limit
- name: continuation_token
in: query
required: false
schema:
type: integer
default: 0
title: Continuation Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResponse_ContextGraphVersionResponse_'
'404':
description: Not found.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/context-graphs/{context_graph_id}/versions/{version}:
get:
tags:
- Context Graphs
summary: Get a context graph version
description: Retrieve a specific context graph version by number, or 'latest'. Requires `ContextGraph.view` permission.
operationId: get-context_graph-version
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: context_graph_id
in: path
required: true
schema:
type: string
format: uuid
title: Context Graph Id
- name: version
in: path
required: true
schema:
anyOf:
- type: integer
- type: string
title: Version
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContextGraphVersionResponse'
'404':
description: Not found.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
FailureClass:
type: string
enum:
- timeout
- input_rejected
- rounds_exhausted
- generic
title: FailureClass
description: 'Why a tool result is a failure — produced by the executor at RUN time.
Unlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime
classification the executor knows at the moment of failure. It flavors the
agent-facing failure wording and the world-event / status-tool observability,
and it is ALSO an optional routing key: a state x tool binding may set
``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class
(e.g. interrupt on timeout, queue on a generic error). With no per-class map
(the default), failed results route by the ``failure_delivery`` floor,
unchanged. Add a member only in the same change that wires a producer for it —
adding one also widens the per-class routing surface, so it must be a
deliberate, produced class.'
AnnotationState:
properties:
type:
type: string
const: annotation
title: Type
name:
type: string
title: Name
inner_thought:
type: string
title: Inner Thought
next_state:
type: string
title: Next State
type: object
required:
- type
- name
- inner_thought
- next_state
title: AnnotationState
description: Injects a hardcoded inner thought (no LLM call).
ChannelOverride:
properties:
objective:
anyOf:
- type: string
- type: 'null'
title: Objective
action_guidelines:
items:
type: string
type: array
title: Action Guidelines
default: []
progress:
anyOf:
- $ref: '#/components/schemas/ProgressHint'
- type: 'null'
type: object
title: ChannelOverride
description: Per-channel behavior override for a state.
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
ContextGraphState-Input:
oneOf:
- $ref: '#/components/schemas/ActionState-Input'
- $ref: '#/components/schemas/DecisionState-Input'
- $ref: '#/components/schemas/AnnotationState'
- $ref: '#/components/schemas/DataCollectionState-Input'
discriminator:
propertyName: type
mapping:
action: '#/components/schemas/ActionState-Input'
annotation: '#/components/schemas/AnnotationState'
data_collection: '#/components/schemas/DataCollectionState-Input'
decision: '#/components/schemas/DecisionState-Input'
ProgressHint:
properties:
deterministic:
type: boolean
title: Deterministic
default: false
phrases:
anyOf:
- items:
type: string
type: array
maxItems: 10
minItems: 1
description: 'Filler phrases. deterministic=true: played verbatim in order. deterministic=false: used as hints for early attempts.'
- type: 'null'
title: Phrases
trigger_delay_ms:
anyOf:
- type: integer
maximum: 30000.0
minimum: 0.0
- type: 'null'
title: Trigger Delay Ms
interval_ms:
anyOf:
- type: integer
maximum: 30000.0
minimum: 100.0
- type: 'null'
title: Interval Ms
mode:
type: string
enum:
- auto
- silent
- backchannel
- verbal
title: Mode
default: auto
progress_class:
anyOf:
- type: string
enum:
- lookup
- write
- external_call
- compute
- multi_step
- type: 'null'
title: Progress Class
expected_latency_ms:
anyOf:
- type: integer
maximum: 60000.0
minimum: 0.0
- type: 'null'
title: Expected Latency Ms
custom_phrase:
anyOf:
- type: string
maxLength: 500
description: 'Legacy: use phrases instead.'
- type: 'null'
title: Custom Phrase
additionalProperties: false
type: object
title: ProgressHint
description: 'How the agent narrates waiting on a tool.
``deterministic=true``: scripted — ``phrases`` play verbatim in order.
``deterministic=false``: engine picks — ``phrases`` are hints.
``trigger_delay_ms``: milliseconds before first filler (0 = immediate).
``interval_ms``: milliseconds between subsequent fillers.'
ActionState-Input:
properties:
type:
type: string
const: action
title: Type
name:
type: string
title: Name
objective:
type: string
title: Objective
actions:
items:
$ref: '#/components/schemas/Action'
type: array
title: Actions
intra_state_navigation_guidelines:
items:
type: string
type: array
title: Intra State Navigation Guidelines
action_guidelines:
items:
type: string
type: array
title: Action Guidelines
boundary_constraints:
items:
type: string
type: array
title: Boundary Constraints
exit_conditions:
items:
$ref: '#/components/schemas/ExitCondition'
type: array
title: Exit Conditions
action_tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Action Tool Call Specs
default: []
exit_condition_tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Exit Condition Tool Call Specs
default: []
wait_for:
anyOf:
- type: string
enum:
- surface_submission
- human_approval
- type: 'null'
title: Wait For
guardrails:
items:
$ref: '#/components/schemas/Guardrail'
type: array
title: Guardrails
default: []
channel_overrides:
additionalProperties:
$ref: '#/components/schemas/ChannelOverride'
type: object
title: Channel Overrides
surface_spec_template:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Surface Spec Template
turn_policy:
anyOf:
- $ref: '#/components/schemas/TurnPolicy'
- type: 'null'
preload:
items:
$ref: '#/components/schemas/PreloadSpec'
type: array
maxItems: 20
title: Preload
type: object
required:
- type
- name
- objective
- actions
- intra_state_navigation_guidelines
- action_guidelines
- boundary_constraints
- exit_conditions
title: ActionState
description: User-facing engagement state with actions and exit conditions.
UpdateContextGraphRequest:
properties:
name:
anyOf:
- $ref: '#/components/schemas/NameString'
- type: 'null'
description:
anyOf:
- $ref: '#/components/schemas/DescriptionString'
- type: 'null'
type: object
title: UpdateContextGraphRequest
ExitCondition:
properties:
description:
type: string
title: Description
next_state:
type: string
title: Next State
filler_hint:
anyOf:
- type: string
- type: 'null'
title: Filler Hint
type: object
required:
- description
- next_state
title: ExitCondition
DecisionState-Input:
properties:
type:
type: string
const: decision
title: Type
name:
type: string
title: Name
objective:
type: string
title: Objective
exit_conditions:
items:
$ref: '#/components/schemas/ExitCondition'
type: array
title: Exit Conditions
decision_guidelines:
items:
type: string
type: array
title: Decision Guidelines
default: []
tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Tool Call Specs
default: []
wait_for:
anyOf:
- type: string
enum:
- surface_submission
- human_approval
- type: 'null'
title: Wait For
guardrails:
items:
$ref: '#/components/schemas/Guardrail'
type: array
title: Guardrails
default: []
channel_overrides:
additionalProperties:
$ref: '#/components/schemas/ChannelOverride'
type: object
title: Channel Overrides
turn_policy:
anyOf:
- $ref: '#/components/schemas/TurnPolicy'
- type: 'null'
type: object
required:
- type
- name
- objective
- exit_conditions
title: DecisionState
description: Passthrough routing state — Agent picks an exit condition, no user interaction.
DecisionState-Output:
properties:
type:
type: string
const: decision
title: Type
name:
type: string
title: Name
objective:
type: string
title: Objective
exit_conditions:
items:
$ref: '#/components/schemas/ExitCondition'
type: array
title: Exit Conditions
decision_guidelines:
items:
type: string
type: array
title: Decision Guidelines
default: []
tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Tool Call Specs
default: []
wait_for:
anyOf:
- type: string
enum:
- surface_submission
- human_approval
- type: 'null'
title: Wait For
guardrails:
items:
$ref: '#/components/schemas/Guardrail'
type: array
title: Guardrails
default: []
channel_overrides:
additionalProperties:
$ref: '#/components/schemas/ChannelOverride'
type: object
title: Channel Overrides
turn_policy:
anyOf:
- $ref: '#/components/schemas/TurnPolicy'
- type: 'null'
type: object
required:
- type
- name
- objective
- exit_conditions
title: DecisionState
description: Passthrough routing state — Agent picks an exit condition, no user interaction.
PaginatedResponse_ContextGraphVersionResponse_:
properties:
items:
items:
$ref: '#/components/schemas/ContextGraphVersionResponse'
type: array
title: Items
has_more:
type: boolean
title: Has More
continuation_token:
anyOf:
- type: integer
- type: 'null'
title: Continuation Token
total:
anyOf:
- type: integer
- type: 'null'
title: Total
type: object
required:
- items
- has_more
title: PaginatedResponse[ContextGraphVersionResponse]
DataCollectionState-Input:
properties:
type:
type: string
const: data_collection
title: Type
name:
type: string
title: Name
objective:
type: string
title: Objective
fields:
items:
$ref: '#/components/schemas/CollectionField'
type: array
title: Fields
on_complete:
type: string
title: On Complete
action_guidelines:
items:
type: string
type: array
title: Action Guidelines
default: []
boundary_constraints:
items:
type: string
type: array
title: Boundary Constraints
default: []
surface_fallback:
type: boolean
title: Surface Fallback
default: false
surface_fallback_after_turns:
type: integer
title: Surface Fallback After Turns
default: 6
max_turns:
type: integer
title: Max Turns
default: 10
guardrails:
items:
$ref: '#/components/schemas/Guardrail'
type: array
title: Guardrails
default: []
channel_overrides:
additionalProperties:
$ref: '#/components/schemas/ChannelOverride'
type: object
title: Channel Overrides
turn_policy:
anyOf:
- $ref: '#/components/schemas/TurnPolicy'
- type: 'null'
tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Tool Call Specs
default: []
type: object
required:
- type
- name
- objective
- fields
- on_complete
title: DataCollectionState
description: 'Structured voice/text data collection with field tracking.
The engine presents fields conversationally, tracks completion, and
optionally falls back to a Surface form after N turns. Each collected
field produces a world.event with confidence 0.5.'
DataCollectionState-Output:
properties:
type:
type: string
const: data_collection
title: Type
name:
type: string
title: Name
objective:
type: string
title: Objective
fields:
items:
$ref: '#/components/schemas/CollectionField'
type: array
title: Fields
on_complete:
type: string
title: On Complete
action_guidelines:
items:
type: string
type: array
title: Action Guidelines
default: []
boundary_constraints:
items:
type: string
type: array
title: Boundary Constraints
default: []
surface_fallback:
type: boolean
title: Surface Fallback
default: false
surface_fallback_after_turns:
type: integer
title: Surface Fallback After Turns
default: 6
max_turns:
type: integer
title: Max Turns
default: 10
guardrails:
items:
$ref: '#/components/schemas/Guardrail'
type: array
title: Guardrails
default: []
channel_overrides:
additionalProperties:
$ref: '#/components/schemas/ChannelOverride'
type: object
title: Channel Overrides
turn_policy:
anyOf:
- $ref: '#/components/schemas/TurnPolicy'
- type: 'null'
tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Tool Call Specs
default: []
type: object
required:
- type
- name
- objective
- fields
- on_complete
title: DataCollectionState
description: 'Structured voice/text data collection with field tracking.
The engine presents fields conversationally, tracks completion, and
optionally falls back to a Surface form after N turns. Each collected
field produces a world.event with confidence 0.5.'
PaginatedResponse_ContextGraphResponse_:
properties:
items:
items:
$ref: '#/components/schemas/ContextGraphResponse'
type: array
title: Items
has_more:
type: boolean
title: Has More
continuation_token:
anyOf:
- type: integer
- type: 'null'
title: Continuation Token
total:
anyOf:
- type: integer
- type: 'null'
title: Total
type: object
required:
- items
- has_more
title: PaginatedResponse[ContextGraphResponse]
PreloadSpec:
properties:
tool_id:
type: string
maxLength: 256
title: Tool Id
params:
additionalProperties: true
type: object
maxProperties: 20
title: Params
type: object
required:
- tool_id
title: PreloadSpec
description: 'A tool call executed deterministically by the engine on state entry.
Unlike LLM-driven tool calls, preloads run before any LLM turn —
the results appear in the interaction log so the engage LLM sees
them as pre-loaded context. All preloads in a state execute in
parallel. Param values support ``{caller_mrn}`` and ``{entity_id}``
template variables resolved from the session''s caller context.'
ActionState-Output:
properties:
type:
type: string
const: action
title: Type
name:
type: string
title: Name
objective:
type: string
title: Objective
actions:
items:
$ref: '#/components/schemas/Action'
type: array
title: Actions
intra_state_navigation_guidelines:
items:
type: string
type: array
title: Intra State Navigation Guidelines
action_guidelines:
items:
type: string
type: array
title: Action Guidelines
boundary_constraints:
items:
type: string
type: array
title: Boundary Constraints
exit_conditions:
items:
$ref: '#/components/schemas/ExitCondition'
type: array
title: Exit Conditions
action_tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Action Tool Call Specs
default: []
exit_condition_tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Exit Condition Tool Call Specs
default: []
wait_for:
anyOf:
- type: string
enum:
- surface_submission
- human_approval
- type: 'null'
title: Wait For
guardrails:
items:
$ref: '#/components/schemas/Guardrail'
type: array
title: Guardrails
default: []
channel_overrides:
additionalProperties:
$ref: '#/components/schemas/ChannelOverride'
type: object
title: Channel Overrides
surface_spec_template:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Surface Spec Template
turn_policy:
anyOf:
- $ref: '#/components/schemas/TurnPolicy'
- type: 'null'
preload:
items:
$ref: '#/components/schemas/PreloadSpec'
type: array
maxItems: 20
title: Preload
type: object
required:
- type
- name
- objective
- actions
- intra_state_navigation_guidelines
- action_guidelines
- boundary_constraints
- exit_conditions
title: ActionState
description: User-facing engagement state with actions and exit conditions.
CreateContextGraphRequest:
properties:
name:
$ref: '#/components/schemas/NameString'
description:
$ref: '#/components/schemas/DescriptionString'
default: ''
type: object
required:
- name
title: CreateContextGraphRequest
ToolCallSpec:
properties:
tool_id:
type: string
t
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-context-graphs-api-openapi.yml