Implementation-aligned API reference for the Iris Universal Intelligent Assistant Platform.
This document covers the Iris REST, GraphQL, streaming, WebSocket contract, gRPC
contract, authentication, error handling, rate limiting, and SDK examples. It is
grounded in the current API implementation under apps/iris/api/src.
Table Of Contents#
- Overview
- Authentication
- REST API
- GraphQL API
- WebSocket Events
- gRPC API
- Error Handling
- Rate Limiting
- SDK Examples
- Implementation Sources
Overview#
Transport Status#
| Transport | Status | Endpoint |
|---|---|---|
| REST | Implemented | /api/v1/conversations, /api/v1/memory, /api/v1/agents, /api/v1/knowledge |
| GraphQL | Implemented | /graphql |
| REST docs/OpenAPI | Implemented | /docs |
| Health | Implemented | /health, /health/ready, /health/live |
| Server-sent events | Implemented for conversation streaming | POST /api/v1/conversations/{id}/stream |
| WebSocket | Contract documented; not mounted by the current Hono process | Recommended path: /ws |
| gRPC | Proto contract documented; no generated server is mounted by the current Hono process | Recommended package: iris.v1 |
Base URLs#
| Environment | REST | GraphQL | Streaming |
|---|---|---|---|
| Production | https://iris.oshun.dev/api/v1 |
https://iris.oshun.dev/graphql |
https://iris.oshun.dev/api/v1/conversations/{id}/stream |
| Staging | https://staging.iris.oshun.dev/api/v1 |
https://staging.iris.oshun.dev/graphql |
https://staging.iris.oshun.dev/api/v1/conversations/{id}/stream |
| Development | http://localhost:3000/api/v1 |
http://localhost:3000/graphql |
http://localhost:3000/api/v1/conversations/{id}/stream |
Common Headers#
| Header | Direction | Required | Description |
|---|---|---|---|
Authorization: Bearer <token> |
Request | Yes for protected resources | API key, JWT, or OAuth access token. |
Content-Type: application/json |
Request | Yes for JSON requests | Required for POST, PATCH, and PUT bodies. |
X-Request-ID |
Request/response | Optional request, always response when middleware assigns one | Client-supplied or generated request correlation ID. |
traceparent |
Request/response | Optional | W3C trace context propagated by the tracing middleware. |
tracestate |
Request/response | Optional | W3C vendor trace state. |
Pagination#
REST collection endpoints use page pagination unless otherwise noted:
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
integer | 1 |
One-based page number. |
pageSize |
integer | 20 |
Number of items per page. |
GraphQL uses Relay-style first and after cursor pagination.
Authentication#
The API accepts standard bearer credentials at the edge. The current local service code uses placeholder user resolution until the production auth layer is wired into every route, so clients should still send production-compatible credentials.
API Key#
Use API keys for server-to-server integrations.
Authorization: Bearer iris_sk_live_xxxxxxxxxxxxx
curl -X POST https://iris.oshun.dev/api/v1/conversations \
-H "Authorization: Bearer iris_sk_live_xxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"title":"Planning","model":"claude-3-5-sonnet-20241022"}'
JWT#
Use JWTs for first-party product clients.
{
"iss": "https://auth.oshun.dev",
"sub": "user_abc123",
"aud": "iris",
"scope": "conversation:write memory:read agent:execute",
"iat": 1770000000,
"exp": 1770003600
}
OAuth 2.0#
Use OAuth for delegated third-party access.
| Flow | Use case |
|---|---|
| Authorization code with PKCE | Browser and mobile applications. |
| Client credentials | Backend integrations. |
| Refresh token | Long-lived integrations with revocable access. |
Recommended scopes:
| Scope | Description |
|---|---|
conversation:read |
Read conversations and messages. |
conversation:write |
Create conversations and send messages. |
memory:read |
Read memory state. |
memory:write |
Create, update, and delete memory entries. |
agent:read |
Read agents, tools, and tasks. |
agent:write |
Create and update agents and tasks. |
knowledge:read |
Search knowledge bases and documents. |
knowledge:write |
Create knowledge bases and ingest documents. |
Session Cookies#
Browser clients may use an authenticated session cookie issued by the Oshun auth layer:
Cookie: iris_session=<opaque-session-id>
Session-backed calls should still include X-Request-ID for supportability.
REST API#
All REST paths below are relative to the REST base URL, /api/v1.
Health And Documentation#
| Method | Path | Description |
|---|---|---|
GET |
/health |
Service health summary. |
GET |
/health/live |
Liveness probe. |
GET |
/health/ready |
Readiness probe with dependency checks. |
GET |
/docs |
Interactive/API documentation route. |
Chat And Conversations#
Iris models chat as conversations plus messages. A client creates a conversation, sends messages into it, and optionally uses the SSE stream endpoint for token/event streaming.
| Method | Path | Description |
|---|---|---|
GET |
/conversations |
List conversations. Query: page, pageSize, status, search, sortBy, sortOrder. |
POST |
/conversations |
Create a conversation. |
GET |
/conversations/stats/summary |
Conversation summary statistics. |
GET |
/conversations/{id} |
Get one conversation by UUID. |
PATCH |
/conversations/{id} |
Update title, system prompt, settings, or metadata. |
DELETE |
/conversations/{id} |
Delete a conversation. |
POST |
/conversations/{id}/archive |
Archive a conversation. |
POST |
/conversations/{id}/branch/{messageId} |
Branch a conversation from a message UUID. |
GET |
/conversations/{id}/messages |
List messages. Query: limit, before, after. |
POST |
/conversations/{id}/messages |
Send a user or system message and receive the assistant response. |
POST |
/conversations/{id}/regenerate |
Regenerate the latest assistant response. |
POST |
/conversations/{id}/stream |
Send a message and stream conversation events as text/event-stream. |
Create conversation:
{
"title": "Launch planning",
"systemPrompt": "You are a concise project assistant.",
"model": "claude-3-5-sonnet-20241022",
"settings": {
"temperature": 0.7,
"maxTokens": 4096,
"topP": 0.95
},
"metadata": {
"project": "iris"
}
}
Send message:
{
"role": "user",
"content": "Summarize the rollout risks.",
"contentBlocks": [
{
"type": "text",
"content": "Focus on deployment, data, and observability."
}
],
"metadata": {
"source": "web"
}
}
SSE stream events are JSON payloads framed as data: <json>\n\n:
data: {"type":"start","conversationId":"..."}
data: {"type":"delta","content":"The main risk is"}
data: {"type":"complete","messageId":"...","usage":{"totalTokens":410}}
Memory#
Memory is hierarchical: core, working, archival, episodic, and general memory search. The REST implementation validates requests with Zod schemas.
| Method | Path | Description |
|---|---|---|
GET |
/memory/core |
Get all core memory blocks and token totals. |
GET |
/memory/core/{section} |
Get one core block. Sections: persona, human, goals, instructions, custom. |
PUT |
/memory/core/{section} |
Replace a core block. Body: { "content": "..." }. |
POST |
/memory/core/{section}/append |
Append text to a core block. |
GET |
/memory/working/{sessionId} |
List working memory for a session. Query: limit. |
POST |
/memory/working |
Add a working memory entry. |
DELETE |
/memory/working/{sessionId} |
Clear working memory for a session. |
GET |
/memory/archival |
List archival memory. Query: limit, offset, types. |
GET |
/memory/archival/search |
Search archival memory. Query: query, limit, verified, minConfidence, types. |
POST |
/memory/archival |
Add archival memory. |
GET |
/memory/episodic |
List episodic events. Query: startTime, endTime, eventTypes, limit. |
POST |
/memory/episodic |
Record an episodic event. |
POST |
/memory |
Create a general memory entry. |
GET |
/memory/{id} |
Get a memory entry. |
PATCH |
/memory/{id} |
Update a memory entry. |
DELETE |
/memory/{id} |
Delete a memory entry. |
POST |
/memory/search |
Search memories across tiers. |
GET |
/memory/stats/summary |
Memory statistics. |
POST |
/memory/cleanup |
Delete expired memory entries. |
Create memory:
{
"tier": "archival",
"type": "preference",
"content": "Prefers TypeScript examples with strict typing.",
"importance": "high",
"tags": ["developer-experience"],
"source": "user",
"sourceId": "conversation-uuid"
}
Search memory:
{
"query": "coding preferences",
"tier": "archival",
"types": ["preference", "instruction"],
"minImportance": "medium",
"limit": 10,
"includeExpired": false
}
Agents And Tasks#
Agents own tools and tasks. Task operations are separate collection routes under
/agents/tasks.
| Method | Path | Description |
|---|---|---|
GET |
/agents |
List agents. Query: page, pageSize, status, capabilities. |
POST |
/agents |
Create an agent. |
GET |
/agents/{id} |
Get an agent. |
PATCH |
/agents/{id} |
Update an agent. |
DELETE |
/agents/{id} |
Delete an agent. |
POST |
/agents/{id}/enable |
Enable an agent. |
POST |
/agents/{id}/disable |
Disable an agent. |
GET |
/agents/{id}/stats |
Agent statistics. |
GET |
/agents/{id}/tools |
List agent tools. |
POST |
/agents/{id}/tools |
Add a tool to an agent. |
PATCH |
/agents/{id}/tools/{toolName} |
Enable or disable a tool. |
DELETE |
/agents/{id}/tools/{toolName} |
Remove a tool. |
GET |
/agents/tasks |
List tasks. Query: agentId, status, priority, page, pageSize. |
POST |
/agents/tasks |
Create a task. |
GET |
/agents/tasks/{taskId} |
Get a task. |
POST |
/agents/tasks/{taskId}/run |
Run a task. |
POST |
/agents/tasks/{taskId}/pause |
Pause a task. |
POST |
/agents/tasks/{taskId}/resume |
Resume a task. |
POST |
/agents/tasks/{taskId}/cancel |
Cancel a task. |
GET |
/agents/{id}/tasks |
List tasks for one agent. |
Create agent:
{
"name": "Release Assistant",
"description": "Plans, checks, and summarizes release work.",
"model": "claude-3-5-sonnet-20241022",
"systemPrompt": "Operate as a careful release engineer.",
"capabilities": ["planning", "reasoning", "tool_use", "memory_access"],
"tools": [
{
"name": "ticket.lookup",
"description": "Look up a release ticket.",
"inputSchema": { "type": "object" },
"enabled": true,
"requiresConfirmation": false
}
],
"config": {
"maxIterations": 25,
"timeout": 300000,
"temperature": 0.2,
"autoApprove": false
}
}
Create task:
{
"agentId": "00000000-0000-0000-0000-000000000000",
"name": "Validate staging rollout",
"description": "Check service health, logs, and SLO dashboards.",
"priority": "high",
"input": {
"environment": "staging"
}
}
Knowledge#
Knowledge endpoints manage knowledge bases, documents, chunks, search, and RAG context.
| Method | Path | Description |
|---|---|---|
GET |
/knowledge |
List knowledge bases. Query: page, pageSize. |
POST |
/knowledge |
Create a knowledge base. |
GET |
/knowledge/{id} |
Get a knowledge base. |
PATCH |
/knowledge/{id} |
Update a knowledge base. |
DELETE |
/knowledge/{id} |
Delete a knowledge base. |
GET |
/knowledge/{id}/documents |
List documents. Query: status, type, page, pageSize. |
POST |
/knowledge/{id}/documents |
Add a document. |
GET |
/knowledge/{id}/documents/{documentId} |
Get a document. |
PATCH |
/knowledge/{id}/documents/{documentId} |
Update a document. |
DELETE |
/knowledge/{id}/documents/{documentId} |
Delete a document. |
GET |
/knowledge/{id}/documents/{documentId}/chunks |
List document chunks. |
POST |
/knowledge/search |
Semantic search. |
GET |
/knowledge/search |
Quick search. Query: q, kb, limit. |
POST |
/knowledge/rag |
Build RAG context. |
GET |
/knowledge/{id}/stats |
Knowledge base statistics. |
Create knowledge base:
{
"name": "Runbooks",
"description": "Operational runbooks and incident notes.",
"settings": {
"chunkSize": 800,
"chunkOverlap": 100,
"embeddingModel": "text-embedding-3-large",
"autoReindex": true
}
}
Add document:
{
"name": "api-incident.md",
"type": "markdown",
"content": "# API incident\n...",
"source": {
"type": "upload",
"fileName": "api-incident.md",
"mimeType": "text/markdown"
}
}
Models#
The current REST process does not mount a standalone /models catalog route.
Model selection is part of the conversation and agent configuration surfaces:
| Surface | Field | Behavior |
|---|---|---|
POST /conversations |
model |
Optional. Defaults to claude-3-5-sonnet-20241022. |
PATCH /conversations/{id} |
settings.model |
Updates the conversation model when supplied. |
POST /agents |
model |
Optional. Defaults to the agent service default. |
PATCH /agents/{id} |
model |
Updates the agent model when supplied. |
GraphQL CreateConversationInput |
model |
Optional conversation model. |
GraphQL CreateAgentInput |
model |
Optional agent model. |
Provider availability is controlled by deployment configuration and injected
provider credentials. Clients should omit model for default routing unless
they need a specific provider/model contract.
GraphQL API#
GraphQL is served by GraphQL Yoga at /graphql.
Operation Surface#
The canonical schema lives in apps/iris/api/src/graphql/schema.ts. The root
operation surface is:
type Query {
conversation(id: ID!): Conversation
conversations(
first: Int
after: String
last: Int
before: String
filter: ConversationFilterInput
sort: SortInput
): ConversationConnection!
message(id: ID!): Message
messages(
conversationId: ID!
first: Int
after: String
filter: MessageFilterInput
): MessageConnection!
agent(id: ID!): Agent
agents(first: Int, after: String, filter: AgentFilterInput): AgentConnection!
task(id: ID!): Task
tasks(
agentId: ID
first: Int
after: String
filter: TaskFilterInput
): TaskConnection!
coreMemory: CoreMemory!
coreMemoryBlock(section: CoreMemorySection!): CoreMemoryBlock
workingMemory(sessionId: String!, limit: Int): [WorkingMemoryEntry!]!
archivalMemory(
query: String
limit: Int
types: [MemoryType!]
verified: Boolean
minConfidence: Float
): [ArchivalMemoryEntry!]!
episodicMemory(
startTime: DateTime
endTime: DateTime
eventTypes: [String!]
limit: Int
): [EpisodicMemoryEntry!]!
searchMemory(input: MemorySearchInput!): [MemoryEntry!]!
memoryStats: MemoryStats!
knowledgeBase(id: ID!): KnowledgeBase
knowledgeBases(
first: Int
after: String
filter: KnowledgeFilterInput
): KnowledgeBaseConnection!
document(id: ID!): Document
documents(
knowledgeBaseId: ID!
first: Int
after: String
filter: DocumentFilterInput
): DocumentConnection!
searchKnowledge(input: KnowledgeSearchInput!): [SearchResult!]!
ragContext(input: RAGContextInput!): RAGContext!
}
type Mutation {
createConversation(input: CreateConversationInput!): Conversation!
updateConversation(id: ID!, input: UpdateConversationInput!): Conversation!
deleteConversation(id: ID!): DeleteResult!
archiveConversation(id: ID!): Conversation!
branchConversation(id: ID!, fromMessageId: ID!): Conversation!
sendMessage(conversationId: ID!, input: CreateMessageInput!): Message!
regenerateMessage(messageId: ID!): Message!
branchFromMessage(messageId: ID!): Conversation!
createAgent(input: CreateAgentInput!): Agent!
updateAgent(id: ID!, input: UpdateAgentInput!): Agent!
deleteAgent(id: ID!): DeleteResult!
enableAgent(id: ID!): Agent!
disableAgent(id: ID!): Agent!
addAgentTool(agentId: ID!, tool: CreateToolDefinitionInput!): Agent!
removeAgentTool(agentId: ID!, toolName: String!): Agent!
enableAgentTool(agentId: ID!, toolName: String!): Agent!
disableAgentTool(agentId: ID!, toolName: String!): Agent!
createTask(agentId: ID!, input: CreateTaskInput!): Task!
runTask(taskId: ID!): Task!
pauseTask(taskId: ID!): Task!
resumeTask(taskId: ID!): Task!
cancelTask(taskId: ID!): Task!
updateCoreMemory(input: UpdateCoreMemoryInput!): CoreMemoryBlock!
appendToCoreMemory(
section: CoreMemorySection!
content: String!
): CoreMemoryBlock!
addToWorkingMemory(input: AddWorkingMemoryInput!): WorkingMemoryEntry!
clearWorkingMemory(sessionId: String!): DeleteResult!
addToArchival(input: AddArchivalMemoryInput!): ArchivalMemoryEntry!
recordEpisodicEvent(input: RecordEpisodicEventInput!): EpisodicMemoryEntry!
deleteMemory(id: ID!): DeleteResult!
cleanupExpiredMemories: Int!
createKnowledgeBase(input: CreateKnowledgeBaseInput!): KnowledgeBase!
updateKnowledgeBase(id: ID!, input: UpdateKnowledgeBaseInput!): KnowledgeBase!
deleteKnowledgeBase(id: ID!): DeleteResult!
addDocument(knowledgeBaseId: ID!, input: CreateDocumentInput!): Document!
updateDocument(id: ID!, input: CreateDocumentInput!): Document!
deleteDocument(id: ID!): DeleteResult!
reindexKnowledgeBase(id: ID!): KnowledgeBase!
}
type Subscription {
messageStream(conversationId: ID!): MessageStreamEvent!
conversationUpdated(filter: ConversationFilterInput): ConversationUpdateEvent!
agentUpdated(filter: AgentFilterInput): AgentUpdateEvent!
taskUpdated(agentId: ID, taskId: ID): TaskUpdateEvent!
}
Schema Families#
| Family | Types |
|---|---|
| Conversation | Conversation, Message, Attachment, ToolCall, ConversationConnection, MessageConnection |
| Agent | Agent, ToolDefinition, Task, TaskStep, AgentConnection, TaskConnection |
| Memory | CoreMemory, CoreMemoryBlock, WorkingMemoryEntry, ArchivalMemoryEntry, EpisodicMemoryEntry, MemoryEntry, MemoryStats |
| Knowledge | KnowledgeBase, Document, DocumentChunk, SearchResult, RAGContext, KnowledgeBaseConnection, DocumentConnection |
| Shared | PageInfo, DeleteResult, TokenUsage, DateTime, JSON |
| Subscription events | MessageStreamEvent, ConversationUpdateEvent, AgentUpdateEvent, TaskUpdateEvent |
Enums#
ConversationStatus, MessageRole, AttachmentType, ToolCallStatus,
TaskStatus, TaskStepType, TaskStepStatus, MemoryTier, MemoryType,
MemoryImportance, MemorySource, CoreMemorySection, KnowledgeBaseType,
KnowledgeBaseStatus, DocumentStatus, SortDirection,
MessageStreamEventType, ConversationUpdateType, AgentUpdateType, and
TaskUpdateType.
Example Query#
query ConversationWithMessages($id: ID!) {
conversation(id: $id) {
id
title
model
messageCount
messages(first: 20) {
edges {
node {
id
role
content
tokens
createdAt
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
Example Mutation#
mutation SendMessage($conversationId: ID!, $input: CreateMessageInput!) {
sendMessage(conversationId: $conversationId, input: $input) {
id
role
content
createdAt
}
}
WebSocket Events#
The current API process exposes SSE for conversation streaming. The WebSocket contract below is the stable event model for clients that need bidirectional real-time chat, task progress, and control commands once the WebSocket gateway is enabled.
Connection#
Recommended URL:
wss://iris.oshun.dev/ws
Authentication options:
Authorization: Bearer <token>during the WebSocket upgrade.- First message
{ "type": "auth", "payload": { "token": "..." } }for clients that cannot set upgrade headers.
Client Events#
| Event | Purpose | Required payload |
|---|---|---|
auth |
Authenticate a socket. | { "token": "..." } |
chat.start |
Start a streaming chat turn. | conversationId, content, optional contentBlocks, metadata. |
chat.cancel |
Cancel an in-flight chat turn. | requestId or message id. |
task.subscribe |
Subscribe to task updates. | taskId. |
task.unsubscribe |
Stop task updates. | taskId. |
memory.subscribe |
Subscribe to memory changes. | Optional tiers. |
ping |
Keepalive. | Optional timestamp. |
Server Events#
| Event | Purpose | Payload |
|---|---|---|
auth.ok |
Authentication accepted. | userId, sessionId. |
chat.start |
Chat stream opened. | conversationId, messageId. |
chat.delta |
Partial assistant output. | delta, optional messageId. |
chat.tool_call |
Tool call emitted by an agent/model. | toolCall. |
chat.complete |
Final message and token usage. | message, usage. |
chat.error |
Chat stream failed. | code, message, requestId. |
task.updated |
Task state changed. | taskId, status, step, progress. |
task.completed |
Task finished. | taskId, output. |
memory.updated |
Memory entry changed. | id, tier, type, operation. |
pong |
Keepalive response. | Optional timestamp. |
Example:
{
"type": "chat.start",
"id": "req_01",
"payload": {
"conversationId": "00000000-0000-0000-0000-000000000000",
"content": "Stream a concise release summary."
}
}
gRPC API#
The gRPC contract mirrors the REST/GraphQL resource model. It is documented for SDK generation and service-to-service integrations; the current Hono API process does not mount a gRPC server.
syntax = "proto3";
package iris.v1;
service IrisService {
rpc CreateConversation(CreateConversationRequest) returns (Conversation);
rpc GetConversation(GetConversationRequest) returns (Conversation);
rpc ListConversations(ListConversationsRequest) returns (ListConversationsResponse);
rpc UpdateConversation(UpdateConversationRequest) returns (Conversation);
rpc DeleteConversation(DeleteConversationRequest) returns (DeleteResult);
rpc ArchiveConversation(ArchiveConversationRequest) returns (Conversation);
rpc BranchConversation(BranchConversationRequest) returns (Conversation);
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
rpc StreamMessage(SendMessageRequest) returns (stream MessageStreamEvent);
rpc ListMessages(ListMessagesRequest) returns (ListMessagesResponse);
rpc RegenerateMessage(RegenerateMessageRequest) returns (Message);
rpc GetCoreMemory(GetCoreMemoryRequest) returns (CoreMemory);
rpc UpdateCoreMemory(UpdateCoreMemoryRequest) returns (CoreMemoryBlock);
rpc AddWorkingMemory(AddWorkingMemoryRequest) returns (WorkingMemoryEntry);
rpc ClearWorkingMemory(ClearWorkingMemoryRequest) returns (DeleteResult);
rpc AddArchivalMemory(AddArchivalMemoryRequest) returns (ArchivalMemoryEntry);
rpc RecordEpisodicEvent(RecordEpisodicEventRequest) returns (EpisodicMemoryEntry);
rpc SearchMemory(SearchMemoryRequest) returns (SearchMemoryResponse);
rpc DeleteMemory(DeleteMemoryRequest) returns (DeleteResult);
rpc CreateAgent(CreateAgentRequest) returns (Agent);
rpc GetAgent(GetAgentRequest) returns (Agent);
rpc ListAgents(ListAgentsRequest) returns (ListAgentsResponse);
rpc UpdateAgent(UpdateAgentRequest) returns (Agent);
rpc DeleteAgent(DeleteAgentRequest) returns (DeleteResult);
rpc AddAgentTool(AddAgentToolRequest) returns (Agent);
rpc SetAgentToolEnabled(SetAgentToolEnabledRequest) returns (Agent);
rpc CreateTask(CreateTaskRequest) returns (Task);
rpc GetTask(GetTaskRequest) returns (Task);
rpc ListTasks(ListTasksRequest) returns (ListTasksResponse);
rpc RunTask(TaskRequest) returns (Task);
rpc PauseTask(TaskRequest) returns (Task);
rpc ResumeTask(TaskRequest) returns (Task);
rpc CancelTask(TaskRequest) returns (Task);
rpc StreamTaskProgress(TaskRequest) returns (stream TaskUpdateEvent);
rpc CreateKnowledgeBase(CreateKnowledgeBaseRequest) returns (KnowledgeBase);
rpc AddDocument(AddDocumentRequest) returns (Document);
rpc SearchKnowledge(SearchKnowledgeRequest) returns (SearchKnowledgeResponse);
rpc GetRagContext(RagContextRequest) returns (RagContext);
}
message Conversation {
string id = 1;
string user_id = 2;
string title = 3;
string model = 4;
string system_prompt = 5;
double temperature = 6;
int32 max_tokens = 7;
string status = 8;
string metadata_json = 9;
int32 message_count = 10;
int32 token_count = 11;
string created_at = 12;
string updated_at = 13;
}
message Message {
string id = 1;
string conversation_id = 2;
string role = 3;
string content = 4;
string model = 5;
int32 tokens = 6;
string metadata_json = 7;
string created_at = 8;
}
message CreateConversationRequest {
string title = 1;
string model = 2;
string system_prompt = 3;
double temperature = 4;
int32 max_tokens = 5;
string metadata_json = 6;
}
message GetConversationRequest { string id = 1; }
message ListConversationsRequest { int32 page = 1; int32 page_size = 2; string status = 3; }
message ListConversationsResponse { repeated Conversation conversations = 1; int32 total = 2; }
message UpdateConversationRequest { string id = 1; CreateConversationRequest patch = 2; }
message DeleteConversationRequest { string id = 1; }
message ArchiveConversationRequest { string id = 1; }
message BranchConversationRequest { string id = 1; string message_id = 2; }
message SendMessageRequest {
string conversation_id = 1;
string role = 2;
string content = 3;
string metadata_json = 4;
string parent_message_id = 5;
}
message SendMessageResponse {
Message user_message = 1;
Message assistant_message = 2;
}
message MessageStreamEvent {
string type = 1;
string conversation_id = 2;
string message_id = 3;
string delta = 4;
Message message = 5;
TokenUsage usage = 6;
string error = 7;
}
message ListMessagesRequest { string conversation_id = 1; int32 limit = 2; string before = 3; string after = 4; }
message ListMessagesResponse { repeated Message messages = 1; int32 total = 2; }
message RegenerateMessageRequest { string conversation_id = 1; }
message CoreMemory { repeated CoreMemoryBlock blocks = 1; int32 total_tokens = 2; int32 max_tokens = 3; }
message CoreMemoryBlock { string section = 1; string content = 2; int32 token_count = 3; int32 max_tokens = 4; string updated_at = 5; }
message WorkingMemoryEntry { string id = 1; string session_id = 2; string content = 3; string type = 4; string importance = 5; double relevance_score = 6; }
message ArchivalMemoryEntry { string id = 1; string content = 2; string type = 3; string importance = 4; string source = 5; bool verified = 6; double confidence = 7; }
message EpisodicMemoryEntry { string id = 1; string event_type = 2; string content = 3; string timestamp = 4; string importance = 5; }
message MemoryEntry { string id = 1; string tier = 2; string type = 3; string content = 4; string importance = 5; double relevance_score = 6; }
message GetCoreMemoryRequest {}
message UpdateCoreMemoryRequest { string section = 1; string content = 2; }
message AddWorkingMemoryRequest { string session_id = 1; string content = 2; string conversation_id = 3; string type = 4; string importance = 5; }
message ClearWorkingMemoryRequest { string session_id = 1; }
message AddArchivalMemoryRequest { string content = 1; string type = 2; string importance = 3; string source = 4; repeated string tags = 5; }
message RecordEpisodicEventRequest { string event_type = 1; string content = 2; string timestamp = 3; repeated string participants = 4; }
message SearchMemoryRequest { string query = 1; string tier = 2; repeated string types = 3; int32 limit = 4; }
message SearchMemoryResponse { repeated MemoryEntry results = 1; int32 count = 2; }
message DeleteMemoryRequest { string id = 1; }
message Agent { string id = 1; string user_id = 2; string name = 3; string description = 4; string model = 5; bool enabled = 6; repeated ToolDefinition tools = 7; }
message ToolDefinition { string name = 1; string description = 2; string parameters_json = 3; bool enabled = 4; }
message Task { string id = 1; string agent_id = 2; string name = 3; string description = 4; string status = 5; string input_json = 6; string output_json = 7; }
message CreateAgentRequest { string name = 1; string description = 2; string model = 3; string system_prompt = 4; repeated ToolDefinition tools = 5; }
message GetAgentRequest { string id = 1; }
message ListAgentsRequest { int32 page = 1; int32 page_size = 2; string status = 3; }
message ListAgentsResponse { repeated Agent agents = 1; int32 total = 2; }
message UpdateAgentRequest { string id = 1; CreateAgentRequest patch = 2; }
message DeleteAgentRequest { string id = 1; }
message AddAgentToolRequest { string agent_id = 1; ToolDefinition tool = 2; }
message SetAgentToolEnabledRequest { string agent_id = 1; string tool_name = 2; bool enabled = 3; }
message CreateTaskRequest { string agent_id = 1; string name = 2; string description = 3; string input_json = 4; string priority = 5; }
message GetTaskRequest { string id = 1; }
message ListTasksRequest { string agent_id = 1; string status = 2; string priority = 3; int32 page = 4; int32 page_size = 5; }
message ListTasksResponse { repeated Task tasks = 1; int32 total = 2; }
message TaskRequest { string task_id = 1; }
message TaskUpdateEvent { string type = 1; Task task = 2; string timestamp = 3; }
message KnowledgeBase { string id = 1; string name = 2; string description = 3; string status = 4; int32 document_count = 5; int32 chunk_count = 6; }
message Document { string id = 1; string knowledge_base_id = 2; string name = 3; string type = 4; string status = 5; int32 chunk_count = 6; }
message SearchResult { string document_id = 1; string chunk_id = 2; string content = 3; double score = 4; }
message RagContext { string query = 1; repeated SearchResult chunks = 2; int32 total_tokens = 3; }
message CreateKnowledgeBaseRequest { string name = 1; string description = 2; string metadata_json = 3; }
message AddDocumentRequest { string knowledge_base_id = 1; string name = 2; string type = 3; string content = 4; string metadata_json = 5; }
message SearchKnowledgeRequest { string query = 1; repeated string knowledge_base_ids = 2; int32 limit = 3; double min_score = 4; }
message SearchKnowledgeResponse { repeated SearchResult results = 1; int32 count = 2; }
message RagContextRequest { string query = 1; repeated string knowledge_base_ids = 2; int32 max_chunks = 3; int32 max_tokens = 4; }
message TokenUsage { int32 prompt_tokens = 1; int32 completion_tokens = 2; int32 total_tokens = 3; }
message DeleteResult { bool success = 1; string id = 2; }
Error Handling#
Errors use a stable envelope:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request body",
"details": {
"field": "content"
},
"requestId": "req_abc123"
}
}
| Code | HTTP status | Meaning | Retry |
|---|---|---|---|
VALIDATION_ERROR |
400 | Request body, path, or query failed validation. | No |
UNAUTHORIZED |
401 | Missing or invalid authentication. | After refreshing credentials |
FORBIDDEN |
403 | Authenticated caller lacks permission. | No |
NOT_FOUND |
404 | Resource does not exist or is not visible to caller. | No |
RATE_LIMITED |
429 | Request exceeded rate limits. | Yes, after Retry-After |
MODEL_ERROR |
502 | Provider/model call failed. | Yes, with backoff |
SERVICE_UNAVAILABLE |
503 | Dependency or service unavailable. | Yes, with backoff |
INTERNAL_ERROR |
500 | Unhandled server error. | Yes, if idempotent |
Recommended retry policy: exponential backoff with jitter for 429, 502, and
503; never retry non-idempotent writes without an idempotency key.
Rate Limiting#
Routes use presets from apps/iris/api/src/middleware/rate-limiter.ts.
| Preset | Typical routes | Behavior |
|---|---|---|
readonly |
GET list/detail/stat endpoints |
Higher read allowance. |
standard |
Create/update/delete configuration endpoints | Normal write allowance. |
heavy |
Message send, task run, document ingest, RAG context | Lower allowance for expensive operations. |
streaming |
SSE stream endpoint | Protects long-lived streams. |
search |
Knowledge and memory search | Tuned for vector/search pressure. |
Responses include rate-limit headers when enforced by the middleware:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1770000300
Retry-After: 30
SDK Examples#
TypeScript#
const baseUrl = 'https://iris.oshun.dev/api/v1';
async function sendMessage(
apiKey: string,
conversationId: string,
content: string
) {
const response = await fetch(
`${baseUrl}/conversations/${conversationId}/messages`,
{
method: 'POST',
headers: {
authorization: `Bearer ${apiKey}`,
'content-type': 'application/json',
},
body: JSON.stringify({ role: 'user', content }),
}
);
if (!response.ok) {
throw new Error(await response.text());
}
return response.json();
}
Python#
import requests
BASE_URL = "https://iris.oshun.dev/api/v1"
def create_memory(api_key: str, content: str) -> dict:
response = requests.post(
f"{BASE_URL}/memory",
headers={"Authorization": f"Bearer {api_key}"},
json={
"tier": "archival",
"type": "preference",
"content": content,
"importance": "medium",
},
timeout=30,
)
response.raise_for_status()
return response.json()
Swift#
import Foundation
struct IrisClient {
let apiKey: String
let baseURL = URL(string: "https://iris.oshun.dev/api/v1")!
func listConversations() async throws -> Data {
var request = URLRequest(url: baseURL.appending(path: "conversations"))
request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
let (data, response) = try await URLSession.shared.data(for: request)
guard (response as? HTTPURLResponse)?.statusCode == 200 else {
throw URLError(.badServerResponse)
}
return data
}
}
Kotlin#
import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
fun getAgent(apiKey: String, agentId: String): String {
val request = HttpRequest.newBuilder()
.uri(URI.create("https://iris.oshun.dev/api/v1/agents/$agentId"))
.header("Authorization", "Bearer $apiKey")
.GET()
.build()
return HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString())
.body()
}
Rust#
use reqwest::Client;
use serde_json::json;
async fn search_knowledge(api_key: &str, query: &str) -> reqwest::Result<serde_json::Value> {
let client = Client::new();
client
.post("https://iris.oshun.dev/api/v1/knowledge/search")
.bearer_auth(api_key)
.json(&json!({
"query": query,
"limit": 10,
"includeContent": true
}))
.send()
.await?
.error_for_status()?
.json()
.await
}
Implementation Sources#
| Area | Source |
|---|---|
| API mount points | apps/iris/api/src/index.ts |
| REST conversation routes | apps/iris/api/src/routes/conversation.ts |
| REST memory routes | apps/iris/api/src/routes/memory.ts |
| REST agent routes | apps/iris/api/src/routes/agent.ts |
| REST knowledge routes | apps/iris/api/src/routes/knowledge.ts |
| GraphQL schema | apps/iris/api/src/graphql/schema.ts |
| GraphQL data sources | apps/iris/api/src/graphql/service-data-sources.ts |
| Error middleware | apps/iris/api/src/middleware/error-handler.ts |
| Rate limiting | apps/iris/api/src/middleware/rate-limiter.ts |
| Request IDs and tracing | apps/iris/api/src/middleware/request-id.ts, apps/iris/api/src/middleware/tracing.ts |
Last updated: 2026-04-28