Quick Start

Get up and running with Raven in under 5 minutes.

Prerequisites

Before you begin, make sure you have:

Access to the Raven API (self-hosted or cloud)
cURL or any HTTP client for testing
Your preferred programming language for integration

1. Register as a Tenant

First, register your application as a tenant to receive your API key:

curl -X POST http://localhost:3000/api/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI App",
    "email": "dev@example.com"
  }'

Response:

Responsejson

{
  "tenant_id": "abc123-xxx-xxx",
  "api_key": "rk_live_xxxxxxxxxxxx",
  "api_key_prefix": "rk_live_",
  "message": "Save your API key securely. It will not be shown again."
}

Important

Save your API key immediately! It won't be shown again. Store it securely in your environment variables.

2. Create a User

Create a user entry for your end-user. The external_ref can be your own user ID:

Create Userbash

curl -X POST http://localhost:3000/api/v1/users \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "user-123",
    "display_name": "John Doe"
  }'

Response:

Responsejson

{
  "user_id": "usr_abc123",
  "tenant_id": "abc123-xxx-xxx",
  "external_ref": "user-123",
  "display_name": "John Doe",
  "created_at": "2024-01-15T10:30:00Z"
}

3. Start a Conversation

Create a conversation to isolate memory for a specific chat session:

Create Conversationbash

curl -X POST http://localhost:3000/api/v1/conversations \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "title": "Planning Session"
  }'

Response:

Responsejson

{
  "conversation_id": "conv_xyz789",
  "user_id": "usr_abc123",
  "title": "Planning Session",
  "message_count": 0,
  "created_at": "2024-01-15T10:35:00Z"
}

4. Store Memory

After each interaction, store the user message and agent response:

Ingest Memorybash

curl -X POST http://localhost:3000/api/v1/memory/ingest \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "conversation_id": "conv_xyz789",
    "user_message": "Remember that I prefer TypeScript over JavaScript",
    "agent_response": "Got it! I will use TypeScript for all code examples going forward."
  }'

Response:

Responsejson

{
  "success": true,
  "interaction_id": "int_def456",
  "buffered": true,
  "message": "Interaction queued for processing"
}

5. Retrieve Context

Before generating a response, query for relevant context:

Query Memorybash

curl -X POST http://localhost:3000/api/v1/memory/query \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "conversation_id": "conv_xyz789",
    "query": "What programming language does the user prefer?"
  }'

Response:

Responsejson

{
  "context": [
    {
      "type": "episodic",
      "content": "User prefers TypeScript over JavaScript",
      "timestamp": "2024-01-15T10:40:00Z",
      "relevance_score": 0.95
    }
  ],
  "facts": [
    "User prefers TypeScript"
  ]
}

Integration Example

Here's how you might integrate Raven into your agent's workflow:

Agent Integration (TypeScript)typescript

import { RavenClient } from '@raven/sdk';

const raven = new RavenClient({
  apiKey: process.env.RAVEN_API_KEY,
  baseUrl: 'http://localhost:3000'
});

async function handleUserMessage(userId: string, conversationId: string, message: string) {
  // 1. Retrieve relevant context
  const context = await raven.memory.query({
    user_id: userId,
    conversation_id: conversationId,
    query: message
  });

  // 2. Generate response with context
  const response = await generateResponse(message, context);

  // 3. Store the interaction
  await raven.memory.ingest({
    user_id: userId,
    conversation_id: conversationId,
    user_message: message,
    agent_response: response
  });

  return response;
}

You're Ready!

You've completed the basic setup. Here's what to explore next:

→API Authentication →Architecture Deep Dive →Encryption & Security →Full Agent Integration Guide