Graine AI
API referencePeople

Get a person's context

What Graine knows about one of your users, by the identifier your app sends.

What Graine knows about one of your users, by the identifier your app sends.

context is null when nothing has been noted yet (memory off for the agent, or no remembered conversation). memories is null when they were not asked for or could not be read in time (memories_available: false); an empty list means the agent remembers nothing about them. Personal details were removed before anything was saved, and no response carries Graine's internal keys.

Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

POST
/v2/people/context
/v2/people/context

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Request Body

application/jsonRequired

agent_id
Required
Agent Id

The agent whose view of the person to read. Its memory scope (This agent only, or Agents that share memory) decides which facts come back; the notes are the workspace's.

identity
Required
PersonIdentity

include_memoriesInclude Memories

Include the remembered facts (current facts only).

Default: true

Response Body

200

The person's context and remembered facts.

agent_id
Required
Agent Id

The agent whose view this is.

identity
Required
PersonIdentityField

contextContext

What was noted; null when nothing has been.

identifiersIdentifiers

The identifiers linked to the person (empty when none are): field, how and when, never a value.

memoriesMemories | null

The current facts the agent remembers; null when not asked for or not readable in time.

memories_availableMemories Available | null

false when the facts could not be read in time (the notes still answer); null when not asked for.

400

1000 — malformed or contradictory input. 1002 — a required parameter is missing.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

404

1200 — no such resource in your organization. A resource belonging to another organization answers 404, never 403.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — a service this endpoint depends on is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X POST "https://api.graine.ai/v2/people/context" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_0123",
    "include_memories": true
  }'

The person's context and remembered facts.

{
  "agent_id": "agt_0123",
  "identity": {
    "field": "user_id"
  },
  "context": {
    "language": {
      "code": "mr",
      "source": "asked",
      "at": "2026-10-24T10:00:00Z"
    },
    "conversations": 3,
    "last_at": "2026-10-24T10:00:00Z",
    "items": [
      {
        "at": "2026-10-24T10:00:00Z",
        "day": "2026-10-24",
        "channel": "phone",
        "agent_id": "agt_0123",
        "topic": "Loan repayment",
        "status": "promised",
        "open_item": "Wants the revised schedule by email",
        "promise": {
          "what": "Pay 4,000 by Friday",
          "due_date": "2026-10-30",
          "state": "open"
        }
      }
    ]
  },
  "identifiers": [
    {
      "id": "lnk_3f9a1c0b2d4e5f60718a",
      "field": "phone",
      "primary": false,
      "source": "api",
      "linked_at": "2026-10-29T10:00:00Z",
      "verified_at": "2026-10-29T10:00:00Z"
    }
  ],
  "memories": [
    {
      "id": "0b6f8a1e-2c4d-4e7f-9a10-3b5c6d7e8f90",
      "text": "Prefers calls after 6 pm",
      "created_at": "2026-10-20T10:00:00Z",
      "updated_at": "2026-10-22T09:30:00Z"
    }
  ],
  "memories_available": true
}

Previous

Get what works for an agent GET

Next

Link identifiers to a person POST