cURL Examples

Reference guide for using the Hindsight API directly with cURL commands.

Authentication

All API requests require an API key in the Authorization header:

-H "Authorization: Bearer your-api-key"

Base URL

All examples use the following base URL:

https://api.hindsight.vectorize.io

Memory Banks

List Banks

curl -X GET https://api.hindsight.vectorize.io/v1/default/banks \
  -H "Authorization: Bearer your-api-key"

Response:

{
  "banks": [
    {
      "bank_id": "my-assistant",
      "name": "my-assistant",
      "disposition": {
        "skepticism": 3,
        "literalism": 3,
        "empathy": 3
      },
      "background": "",
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:30:00Z"
    }
  ]
}

Get a Bank

curl -X GET https://api.hindsight.vectorize.io/v1/default/banks/my-assistant \
  -H "Authorization: Bearer your-api-key"

Retain (Store Memories)

Basic Retain

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "The user prefers dark mode and concise responses."
      }
    ]
  }'

Response:

{
  "success": true,
  "bank_id": "my-assistant",
  "items_count": 1,
  "async": false,
  "operation_id": null,
  "usage": {
    "input_tokens": 2684,
    "output_tokens": 511,
    "total_tokens": 3195
  }
}

Multiple Items

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "User works in the tech industry"
      },
      {
        "content": "User prefers morning meetings"
      },
      {
        "content": "User is based in San Francisco"
      }
    ]
  }'

With Context and Timestamp

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "Customer reported a checkout issue with error code E-1234.",
        "context": "support_ticket",
        "timestamp": "2024-03-15T10:00:00Z"
      }
    ]
  }'

Async Processing

For large batches, use async mode to process in the background:

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"content": "First memory"},
      {"content": "Second memory"},
      {"content": "Third memory"}
    ],
    "async": true
  }'

Response includes an operation ID for tracking:

{
  "success": true,
  "bank_id": "my-assistant",
  "items_count": 3,
  "async": true,
  "operation_id": "op_abc123"
}

Recall (Search Memories)

Basic Search

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the user preferences?"
  }'

Response:

{
  "results": [
    {
      "id": "mem_123abc",
      "text": "User prefers dark mode and concise responses",
      "type": "world",
      "entities": ["user"],
      "context": "",
      "mentioned_at": "2024-03-15T10:30:00Z"
    }
  ],
  "entities": {
    "user": {
      "entity_id": "ent_456",
      "canonical_name": "user",
      "observations": []
    }
  }
}

Filter by Type

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user preferences",
    "types": ["observation"]
  }'

With Trace (Debug Mode)

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "project deadlines",
    "trace": true
  }'

With Query Timestamp

For temporal queries like "last week" or "in March":

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What happened last week?",
    "query_timestamp": "2024-03-15T10:00:00"
  }'

Reflect (Reasoning Over Memories)

Basic Question

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/reflect \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What should I know about this customer before our call?"
  }'

Response:

{
  "text": "Based on the stored memories, this customer prefers concise communication and dark mode interfaces...",
  "based_on": [],
  "structured_output": null,
  "usage": {
    "input_tokens": 3352,
    "output_tokens": 806,
    "total_tokens": 4158
  }
}

With Context

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/reflect \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the main concerns?",
    "context": "We are preparing for a quarterly business review meeting"
  }'

With Structured Output

Request a specific JSON structure in the response:

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/reflect \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Summarize the key points about this user",
    "response_schema": {
      "type": "object",
      "properties": {
        "summary": {"type": "string"},
        "key_points": {
          "type": "array",
          "items": {"type": "string"}
        }
      },
      "required": ["summary", "key_points"]
    }
  }'

Mental Models

Mental models are user-curated pre-computed reflections generated from a reflect query that stay current as memories change.

Create a Mental Model

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Profile",
    "source_query": "What do we know about this user?"
  }'

Response:

{
  "operation_id": "op_abc123"
}

Create with Options

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team Directory",
    "source_query": "Who works here and what do they do?",
    "tags": ["team", "directory"],
    "max_tokens": 4096,
    "trigger": {
      "refresh_after_consolidation": true
    }
  }'

List Mental Models

curl -X GET https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models \
  -H "Authorization: Bearer your-api-key"

Response:

{
  "items": [
    {
      "id": "mm_abc123",
      "bank_id": "my-assistant",
      "name": "User Profile",
      "source_query": "What do we know about this user?",
      "content": "The user is a software engineer who prefers dark mode...",
      "tags": [],
      "max_tokens": 2048,
      "trigger": {
        "refresh_after_consolidation": false
      },
      "last_refreshed_at": "2024-03-15T10:30:00Z",
      "created_at": "2024-03-15T10:30:00Z"
    }
  ]
}

Get a Mental Model

curl -X GET https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models/mm_abc123 \
  -H "Authorization: Bearer your-api-key"

Update a Mental Model

curl -X PATCH https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models/mm_abc123 \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Profile",
    "source_query": "What are the user'\''s key preferences?"
  }'

Refresh a Mental Model

Re-run the source query to update the content with current memories:

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models/mm_abc123/refresh \
  -H "Authorization: Bearer your-api-key"

Response:

{
  "operation_id": "op_def456"
}

Delete a Mental Model

curl -X DELETE https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models/mm_abc123 \
  -H "Authorization: Bearer your-api-key"

Error Responses

401 Unauthorized

{
  "detail": "Invalid or expired API key"
}

404 Not Found

{
  "detail": "Bank with ID 'invalid-bank' not found"
}

400 Bad Request

{
  "detail": "Validation error: items is required"
}

402 Payment Required

{
  "detail": "Insufficient credits to complete this operation"
}

Tips

Debug Mode

Add -v for verbose output to debug connection issues:

curl -v -X GET https://api.hindsight.vectorize.io/v1/default/banks \
  -H "Authorization: Bearer your-api-key"

Pretty Print with jq

curl -s -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}' | jq '.'

Save Response to File

curl -s -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}' > response.json

Read Content from File

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d @request.json

Where request.json contains:

{
  "items": [
    {"content": "Your content here..."}
  ]
}