Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orinadus.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

POST /ingest HTTP/1.1
Host: 127.0.0.1:18799
Content-Type: application/json
Authorization: Bearer <token>   ← required only if intake_token is configured

​
Request body

All fields except the required ones are optional. Optional fields absent from the body are omitted from the JSONL line on disk (no null keys written).
​
id
string
required
RFC 4122 UUID v4. Must be generated client-side. Used as a deduplication key. Example: "56816532-adb7-4000-8a0f-1dda8408aab5"
​
timestamp
string
required
RFC 3339 UTC timestamp. Example: "2026-05-04T20:00:00Z"
​
source
string
required
Tool or system that produced the event. Must not be blank after trim. Examples: "claude", "copilot", "cli", "ci", "my-script".
​
kind
string
required
Event kind. Accepted values:
ValueUse case
conversationAI chat turn, notes, conversational content
agentAgent-generated reflection or decision
commandShell command, CLI invocation
commitGit commit
fileFile creation, edit, or deletion
decisionArchitectural or product decision
<other>Any other string is stored as Other(value)
​
content
string
required
The memory payload. Must not be blank after trim.
​
workspace
string
Absolute path to the repo or workspace this event belongs to.
​
session
string
Session identifier. Examples: Copilot session UUID, tmux session name.
​
title
string
Short human-readable title for display in vault projections and urchin_status output.
​
tags
string[]
Free-form tags. Omitted from JSONL if empty.
​
actor
object
Identity envelope.
{
  "account": "samhc",
  "device": "saucemachine",
  "workspace": "/home/user/dev/project"
}
All sub-fields are optional. The entire actor field is omitted from JSONL if not provided.
​
brain
string
Vault identifier for multi-brain setups. Optional.

​
Responses

​
200 OK — written

{
  "id": "56816532-adb7-4000-8a0f-1dda8408aab5",
  "status": "ok"
}
Event was validated and written to the journal.

​
202 Accepted — ephemeral drop

{
  "id": "56816532-adb7-4000-8a0f-1dda8408aab5",
  "status": "dropped",
  "reason": "ephemeral"
}
Ephemeral mode is active. The event was accepted but permanently discarded. Nothing written to disk.

​
400 Bad Request — validation failure

content or source is present but blank (empty or whitespace-only after trim). 
{"error": "content must not be empty"}

{"error": "source must not be empty"}

​
401 Unauthorized — auth failure

intake_token is configured and the Authorization header is missing, uses the wrong prefix, or contains the wrong token. 
{"error": "unauthorized"}
Token comparison is string equality. The Bearer prefix (capital B, one space) is required.

​
422 Unprocessable Entity — schema failure

Body is not valid JSON, or one of the required fields (id, timestamp, source, kind, content) is absent from the body. Response body is Axum’s default JSON extractor error — not normalised to the error envelope above.

​
500 Internal Server Error — write failure

journal.append() failed (disk full, permission error, mutex poisoned). 
{"error": "No space left on device"}

​
Examples

curl -s -X POST http://127.0.0.1:18799/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "id": "56816532-adb7-4000-8a0f-1dda8408aab5",
    "timestamp": "2026-05-04T20:00:00Z",
    "source": "copilot",
    "kind": "conversation",
    "content": "Hardened intake auth and added journal write lock."
  }'

​
JSONL on-disk format

Each successful POST /ingest appends one line: 
{"id":"56816532-adb7-4000-8a0f-1dda8408aab5","timestamp":"2026-05-04T20:00:00Z","source":"copilot","kind":"conversation","content":"Hardened intake auth.","workspace":"/home/user/dev/project","tags":["substrate"]}
None optional fields are omitted. Empty tags are omitted.