> ## Documentation Index > Fetch the complete documentation index at: https://docs.get-exo.com/llms.txt > Use this file to discover all available pages before exploring further. # Recall cognitive state > Read one view of the cognitive state Exo has built for the effective subject. `recall_type` is one of `identity` (manifold position, voice profile, recent patterns), `graph` (nodes, edges and domains), `insights` (pending graph proposals) or `temporal` (phases and time structure). Any other value returns 404. Every view is scoped to the caller's org; there is no cross-org read. A freshly imported org returns empty collections until the background cognition cycle has run. The response is one of four documented shapes, told apart by the `type` field every one of them carries. ## Authorization This route requires the `read` scope. A missing or invalid credential returns 401 [`authentication_error`](/errors/authentication_error). A valid credential without the scope returns 403 [`permission_denied`](/errors/permission_denied), and the problem body names the exact scope required. ## Headers These are request conventions the contract does not declare as parameters, so they do not appear in the schema tables below. | Header | Applies | What it does | | ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `X-Exo-API-Key` | Required | Your Exo API key, `exo__`. `Authorization: Bearer exo_...` is accepted as an alternate. | | `X-Exo-Subject` | Optional | Acts for a provisioned subject instead of the key owner. An unprovisioned id returns 403 [`subject_not_provisioned`](/errors/subject_not_provisioned). | | `Idempotency-Key` | Not applicable | The replay engine covers POST requests only. | | `X-Request-Id` | Response | Returned on every response, including `204`s. Quote it in a support request. | ## Success responses | Status | Meaning | | ------ | ----------------------------------- | | `200` | The requested cognitive-state view. | ## Errors | Status | Code | When | | ------ | ------------------------------------------------------ | -------------------------------------------------------------- | | `400` | [`invalid_request`](/errors/invalid_request) | Malformed request, for example an invalid cursor. | | `401` | [`authentication_error`](/errors/authentication_error) | Missing or invalid credentials. | | `403` | [`permission_denied`](/errors/permission_denied) | Missing scope, or an unprovisioned subject selector. | | `404` | [`not_found`](/errors/not_found) | The resource does not exist, or is not visible to this caller. | | `409` | [`conflict`](/errors/conflict) | A conflict with the current state of the resource. | | `422` | [`validation_error`](/errors/validation_error) | The request was understood but failed field validation. | | `429` | [`rate_limit_exceeded`](/errors/rate_limit_exceeded) | Rate limit exceeded. Retry after the Retry-After interval. | | `503` | [`service_degraded`](/errors/service_degraded) | A dependency is temporarily unavailable. Safe to retry. | Every error is an RFC 9457 `application/problem+json` body carrying a stable `code`, a `requestId`, and a `suggestedAction` where Exo has one. See [Errors](/platform/errors). ## Notes * **One route, four views.** `recall_type` is `identity`, `graph`, `insights` or `temporal`, and each returns a different response shape. Any other value is 404. * **Empty collections are the correct answer for a new organization.** The views are built by the background cognition cycle, so a freshly imported organization reads empty until it has run. * **Pagination is opt-in and not available on every view.** Sending `cursor` or `pageSize` to a view that is not a list returns 400 `pagination_unsupported`. ## OpenAPI ````yaml openapi.json GET /v1/recall/{recall_type} openapi: 3.1.0 info: contact: name: Exo url: https://get-exo.com/ description: >- The Exo public developer API: ingest content, retrieve identity-conditioned context, and read the knowledge graph. Authenticate every request with an Exo API key, either as the X-Exo-API-Key header or as Authorization: Bearer exo_... . Errors follow RFC 9457 problem+json with a stable snake_case code on every body. title: Exo API version: 1.0.0 servers: - url: https://api.get-exo.com security: - ApiKeyHeader: [] - BearerAuth: [] tags: - name: retrieve x-group: Retrieval - name: search x-group: Search - name: ingest x-group: Ingestion - name: jobs x-group: Jobs - name: subjects x-group: Subjects - name: recall x-group: Recall - name: graph x-group: Graph - name: insights x-group: Contradictions and proposals - name: condition x-group: Condition - name: brain x-group: Brain - name: sessions x-group: Coding sessions - name: connectors x-group: Connectors - name: events x-group: Events and webhooks - name: meta x-group: Identity - name: keys x-group: Keys and sandbox - name: usage x-group: Usage - name: settings x-group: Settings - name: exports x-group: Exports - name: team x-group: Team - name: admin x-group: Account and purge paths: /v1/recall/{recall_type}: get: tags: - recall summary: Recall cognitive state description: >- Read one view of the cognitive state Exo has built for the effective subject. `recall_type` is one of `identity` (manifold position, voice profile, recent patterns), `graph` (nodes, edges and domains), `insights` (pending graph proposals) or `temporal` (phases and time structure). Any other value returns 404. Every view is scoped to the caller's org; there is no cross-org read. A freshly imported org returns empty collections until the background cognition cycle has run. The response is one of four documented shapes, told apart by the `type` field every one of them carries. operationId: getRecall parameters: - in: path name: recall_type required: true schema: title: Recall Type type: string - description: >- Opaque cursor from a previous nextCursor. Supported on the list-shaped views (insights, temporal). in: query name: cursor required: false schema: anyOf: - type: string - type: 'null' description: >- Opaque cursor from a previous nextCursor. Supported on the list-shaped views (insights, temporal). title: Cursor - description: >- Page size, coerced into [1, 100] (default 25). Supplying it (or a cursor) switches the list-shaped views to a paginated response. in: query name: pageSize required: false schema: anyOf: - type: integer - type: 'null' description: >- Page size, coerced into [1, 100] (default 25). Supplying it (or a cursor) switches the list-shaped views to a paginated response. title: Pagesize responses: '200': content: application/json: schema: additionalProperties: true discriminator: mapping: graph: $ref: '#/components/schemas/RecallGraphResponse' identity: $ref: '#/components/schemas/RecallIdentityResponse' insights: $ref: '#/components/schemas/RecallInsightsResponse' temporal: $ref: '#/components/schemas/RecallTemporalResponse' propertyName: type oneOf: - $ref: '#/components/schemas/RecallIdentityResponse' - $ref: '#/components/schemas/RecallGraphResponse' - $ref: '#/components/schemas/RecallInsightsResponse' - $ref: '#/components/schemas/RecallTemporalResponse' title: CognitiveStateView type: object description: The requested cognitive-state view. '400': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Malformed request, for example an invalid cursor. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Missing or invalid credentials. '403': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Missing scope or unprovisioned subject. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: The requested resource does not exist. '409': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Conflict, for example a duplicate in-flight idempotent request. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Validation Error '429': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- Rate limit exceeded; retry after the interval in the Retry-After header. '503': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: A dependency is temporarily unavailable; safe to retry with backoff. components: schemas: RecallGraphResponse: description: >- The graph view of cognitive state: a drawable viewport plus honest totals. ``nodeCount`` and ``edgeCount`` are the true totals for the subject, while ``nodes`` and ``edges`` are a bounded, mutually consistent page of them: the highest-degree nodes and exactly the edges induced on that set. Use the counts for headline numbers and the lists for drawing. properties: domainCount: description: Total discovered domains the subject participates in. title: Domaincount type: integer domains: description: The largest domains, for a coverage view. items: $ref: '#/components/schemas/RecallDomain' title: Domains type: array edgeCount: description: Total edges between nodes the subject owns. title: Edgecount type: integer edges: description: Exactly the edges induced on the served nodes. items: $ref: '#/components/schemas/RecallGraphEdge' title: Edges type: array nodeCount: description: Total nodes the subject owns. title: Nodecount type: integer nodes: description: The highest-degree slice of the graph. items: $ref: '#/components/schemas/RecallGraphNode' title: Nodes type: array type: const: graph description: Names the view, always 'graph'. title: Type type: string required: - type - nodeCount - edgeCount - domainCount title: RecallGraphResponse type: object RecallIdentityResponse: description: >- The identity view of cognitive state: who Exo has learned the subject to be. Every facet fills in independently as the background cognition cycle warms, so a freshly imported subject gets this envelope with null manifold state, no voice profile and empty lists rather than an error. properties: basinHistory: description: >- Recorded snapshots of the subject's position on the identity surface, oldest first. Empty until snapshots have been taken. items: additionalProperties: true type: object title: Basinhistory type: array contradictions: description: Points where the subject changed their mind, most recent first. items: $ref: '#/components/schemas/IdentityContradiction' title: Contradictions type: array manifoldState: anyOf: - $ref: '#/components/schemas/ManifoldState' - type: 'null' description: >- The discovered surface of how the subject thinks. Null before the first discovery pass. recentPatterns: description: Observed behavioural patterns, strongest first. items: $ref: '#/components/schemas/IdentityPattern' title: Recentpatterns type: array type: const: identity description: Names the view, always 'identity'. title: Type type: string voiceProfile: anyOf: - $ref: '#/components/schemas/VoiceProfile' - type: 'null' description: How the subject writes. Null until there is evidence behind it. required: - type title: RecallIdentityResponse type: object RecallInsightsResponse: description: 'The insights view of cognitive state: connections awaiting approval.' properties: hasMore: anyOf: - type: boolean - type: 'null' description: Whether further pages exist. Present only on a paginated call. title: Hasmore items: description: Proposed connections, newest first. items: $ref: '#/components/schemas/Insight' title: Items type: array nextCursor: anyOf: - type: string - type: 'null' description: >- Cursor for the next page. Present only when the call opted into pagination by supplying a cursor or a page size. title: Nextcursor type: const: insights description: Names the view, always 'insights'. title: Type type: string required: - type title: RecallInsightsResponse type: object RecallTemporalResponse: description: 'The temporal view of cognitive state: the subject''s history as chapters.' properties: hasMore: anyOf: - type: boolean - type: 'null' description: Whether further pages exist. Present only on a paginated call. title: Hasmore nextCursor: anyOf: - type: string - type: 'null' description: >- Cursor for the next page. Present only when the call opted into pagination by supplying a cursor or a page size. title: Nextcursor phases: description: Discovered phases of the subject's history. items: $ref: '#/components/schemas/Phase' title: Phases type: array type: const: temporal description: Names the view, always 'temporal'. title: Type type: string required: - type title: RecallTemporalResponse type: object Problem: description: |- RFC 9457 problem+json envelope (spec D9), documented in OpenAPI. Invariant: ``code`` equals the tail of the ``type`` URI (``https://docs.get-exo.com/errors/``). properties: code: title: Code type: string detail: title: Detail type: string documentationUrl: anyOf: - type: string - type: 'null' title: Documentationurl errors: anyOf: - items: $ref: '#/components/schemas/FieldViolation' type: array - type: 'null' title: Errors requestId: default: '' title: Requestid type: string status: title: Status type: integer suggestedAction: anyOf: - type: string - type: 'null' title: Suggestedaction title: title: Title type: string type: title: Type type: string required: - type - title - status - detail - code title: Problem type: object RecallDomain: description: A discovered topic cluster the subject's knowledge organises into. properties: description: anyOf: - type: string - type: 'null' description: Generated description of the domain, when one exists. title: Description domainId: description: Stable id of the domain. title: Domainid type: string name: description: >- Human-readable domain label, resolved at read time from the domain's most central member content. title: Name type: string nodeCount: description: How many of the subject's nodes sit in this domain. title: Nodecount type: integer required: - domainId - name - nodeCount title: RecallDomain type: object RecallGraphEdge: description: >- One edge in the knowledge-graph viewport returned by the graph recall view. Every served edge has both endpoints inside the served node set, so the viewport is always drawable exactly as given. properties: edgeType: anyOf: - type: string - type: 'null' description: The kind of relation. title: Edgetype source: description: Id of the source node. title: Source type: string target: description: Id of the target node. title: Target type: string weight: description: Strength of the relation. title: Weight type: number required: - source - target - weight title: RecallGraphEdge type: object RecallGraphNode: description: >- One node in the knowledge-graph viewport returned by the graph recall view. properties: authority: description: How much weight the node carries in retrieval, from 0 to 1. title: Authority type: number domain: anyOf: - type: string - type: 'null' description: The discovered domain the node sits in, when one is known. title: Domain nodeId: description: Stable id of the node. title: Nodeid type: string nodeType: description: Whether the node is an anchor, a phase or derived content. title: Nodetype type: string title: anyOf: - type: string - type: 'null' description: Display label for the node. title: Title required: - nodeId - nodeType - authority title: RecallGraphNode type: object IdentityContradiction: description: >- A point where the subject changed their mind, mined from their own history. Exo keeps both sides rather than resolving them: ``beforeText`` is what the subject used to hold and ``afterText`` is what replaced it. The list is empty on an org whose contradiction store has not been built yet. properties: afterText: anyOf: - type: string - type: 'null' description: What replaced it. title: Aftertext beforeText: anyOf: - type: string - type: 'null' description: What was held before. title: Beforetext createdAt: anyOf: - type: string - type: 'null' description: >- Date of the underlying content, as an ISO 8601 date. Null when undated. title: Createdat id: description: Stable id of the detected contradiction. title: Id type: string kind: description: >- Whether this is a retraction of a belief or a reversal between two positions. title: Kind type: string marker: anyOf: - type: string - type: 'null' description: The phrase in the subject's own words that flagged the change. title: Marker title: description: >- Short topic label, falling back to the raw marker until one is generated. title: Title type: string required: - id - kind - title title: IdentityContradiction type: object ManifoldState: additionalProperties: true description: >- The discovered shape of how a subject thinks. Exo does not assume a fixed personality vocabulary. It decomposes the subject's own signals to DISCOVER the axes their thinking actually varies along, then clusters positions on those axes into basins: the stable modes they keep returning to. This object is the state of that surface for one subject. It appears on the identity recall view once the background cognition cycle has run at least one discovery pass; it is null before that, and on a subject with too few signals to decompose. Field names are the stored discovery keys, so this object is snake_case where the rest of the API is camelCase, and it is deliberately open: a pass records diagnostic keys beyond the ones named here and every one of them is passed through unchanged. properties: basin_centers: anyOf: - items: items: type: number type: array type: array - type: 'null' description: Coordinates of each basin centre along the discovered axes. title: Basin Centers basins: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' description: >- The stable modes of thinking the subject returns to, each with its label and size. Present once clustering succeeds. title: Basins cumulative_variance: anyOf: - type: number - type: 'null' description: Total share of variation the kept axes explain. title: Cumulative Variance dimensions: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' description: >- The discovered cognitive axes, each with its label and the poles it runs between. Derived from the subject's own content, not chosen from a fixed list. title: Dimensions discovered_at: anyOf: - type: string - type: 'null' description: When this discovery pass ran, as an ISO 8601 timestamp. title: Discovered At n_basins: anyOf: - type: integer - type: 'null' description: How many stable modes the pass found. title: N Basins n_dimensions: anyOf: - type: integer - type: 'null' description: How many cognitive axes the pass kept. title: N Dimensions n_signals: anyOf: - type: integer - type: 'null' description: How many identity signals the pass decomposed. title: N Signals refresh_count: anyOf: - type: integer - type: 'null' description: How many discovery passes have run for this subject. title: Refresh Count silhouette_score: anyOf: - type: number - type: 'null' description: How cleanly separated the basins are, from -1 to 1. title: Silhouette Score trajectory: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' description: >- Where the subject has sat on the surface over time, oldest first. Present once there is enough dated history to reconstruct it. title: Trajectory variance_ratios: anyOf: - items: type: number type: array - type: 'null' description: Share of the subject's variation each axis explains. title: Variance Ratios version: anyOf: - type: integer - type: 'null' description: Schema version of the stored discovery record. title: Version title: ManifoldState type: object IdentityPattern: description: >- A behavioural regularity Exo has observed in the subject. Patterns are extracted from the subject's own content and ranked by confidence. They describe how the subject tends to work rather than what they know. The list is empty until identity extraction has run. properties: confidence: anyOf: - type: number - type: 'null' description: How strongly the evidence supports the pattern, from 0 to 1. title: Confidence description: anyOf: - type: string - type: 'null' description: What the pattern is. title: Description observedBehavior: anyOf: - type: string - type: 'null' description: The behaviour that evidenced it. title: Observedbehavior patternType: description: Category of the observed pattern. title: Patterntype type: string required: - patternType title: IdentityPattern type: object VoiceProfile: description: >- How the subject writes, measured from their own words. Exo derives this from the subject's stored content rather than asking them, and uses it to make generated text sound like them instead of like a model. It appears on the identity recall view only once there is evidence behind it: a subject whose ``evidenceCount`` is still zero gets null rather than a profile of defaults, because a confidently wrong voice is worse than no voice. properties: avgMessageLengthWords: anyOf: - type: number - type: 'null' description: Mean length of the subject's own messages, in words. title: Avgmessagelengthwords evidenceCount: anyOf: - type: integer - type: 'null' description: >- How many of the subject's messages the profile was measured from. The profile is withheld entirely while this is zero. title: Evidencecount formalityLevel: anyOf: - type: number - type: 'null' description: >- How formal the subject's writing runs, from 0 (casual) to 1 (formal). title: Formalitylevel technicalDepth: anyOf: - type: number - type: 'null' description: >- How technical the subject's vocabulary runs, from 0 (plain) to 1 (dense). title: Technicaldepth title: VoiceProfile type: object Insight: description: >- A connection Exo proposes between two things the subject knows. Insights are the graph's suggestions, not its conclusions: each one waits for approval before it becomes an edge. The rationale names the terms the two endpoints actually share, so a caller can judge the suggestion instead of trusting a score. Only endpoints the subject owns and authored are eligible, which is why a busy agent transcript does not flood this view. properties: confidence: anyOf: - type: number - type: 'null' description: How strongly the proposal is supported, from 0 to 1. title: Confidence edgeType: anyOf: - type: string - type: 'null' description: The kind of edge being proposed. title: Edgetype proposalId: description: Stable id of the proposal. title: Proposalid type: string rationale: anyOf: - type: string - type: 'null' description: >- The content terms the two endpoints share, or null when the overlap is not meaningful enough to name. title: Rationale sourceNodeId: description: Id of the first endpoint. title: Sourcenodeid type: string sourceTitle: description: >- Display label for the first endpoint, resolved from its title or content. title: Sourcetitle type: string targetNodeId: description: Id of the second endpoint. title: Targetnodeid type: string targetTitle: description: >- Display label for the second endpoint, resolved from its title or content. title: Targettitle type: string required: - proposalId - sourceNodeId - targetNodeId - sourceTitle - targetTitle title: Insight type: object Phase: description: >- A chapter of the subject's history, discovered rather than declared. Exo clusters dated content into phases so that time is a structure it can reason over instead of just a sort key: "what was I working on last spring" resolves to a phase rather than to a date range the caller has to guess. Phases appear on the temporal recall view once the background cognition cycle has clustered enough dated content; a freshly imported subject has none. The title reads "Mon YYYY: topic", with the topic resolved at read time from the phase's own member content. properties: nodeId: description: Stable id of the phase. title: Nodeid type: string title: description: 'Human-readable phase label, in the form ''Mon YYYY: topic''.' title: Title type: string required: - nodeId - title title: Phase type: object FieldViolation: description: A single field-level violation inside a Problem ``errors[]`` list. properties: code: title: Code type: string field: title: Field type: string message: title: Message type: string pointer: title: Pointer type: string required: - pointer - field - code - message title: FieldViolation type: object securitySchemes: ApiKeyHeader: description: An Exo API key (exo_...) sent as the X-Exo-API-Key header. in: header name: X-Exo-API-Key type: apiKey BearerAuth: description: The same Exo API key (exo_...) sent as an Authorization bearer token. scheme: bearer type: http ````