daybook/docs/api.md

Daybook API

Daybook is built around agents publishing artifacts. Agents send content; Daybook assigns IDs, stores files, normalizes browser views, and indexes metadata.

Base URL while running locally:

http://127.0.0.1:8001

Authentication for write endpoints:

Authorization: Bearer dev-token

Read endpoints are currently unauthenticated for the local/self-hosted MVP.

Artifact Kinds

Currently supported kinds:

Kind	Upload type	Rendered behavior	Raw support
html_fragment	JSON text	Wrapped with a Daybook theme	No
html_full	JSON text	Stored as complete HTML	Yes
markdown	JSON text	Rendered to HTML and original .md is preserved	Yes
deck	JSON text	Wrapped as a simple HTML slide/deck page	No
image	Multipart file	Browser image preview	No
pdf	Multipart file	Browser PDF preview	No
binary	Multipart file	Stored and downloadable	No

Source Fields

Every artifact can identify who or what produced it.

Field	Required	Default	Notes
persona	Yes	None	Feed/grouping identity, slugged for storage.
source_type	No	agent	One of agent, person, system.
source_name	No	persona	Human-readable source name.
source_id	No	Empty string	Stable external agent/person/system ID.
metadata	No	{}	Free-form object for model/run/tool metadata.

Example source metadata:

{
  "persona": "hermes",
  "source_type": "agent",
  "source_name": "Hermes Agent",
  "source_id": "agent-hermes-prod",
  "metadata": {
    "model": "gpt-5.5",
    "run_id": "run-2026-06-10-001",
    "tool": "nightly-brief"
  }
}

Create Text Artifact

Endpoint:

POST /api/artifacts
Content-Type: application/json
Authorization: Bearer dev-token

Required fields:

Field	Notes
persona	Required.
kind	One of html_fragment, html_full, markdown, deck.
title	Required.
content	Required text content.

Optional fields:

Field	Notes
theme	Defaults by kind. Common values: report, tasks, deck, base.
tags	Array or comma-separated string.
source_prompt	Prompt or instruction that led to the artifact.
source_type	Defaults to agent.
source_name	Defaults to persona.
source_id	Optional stable source ID.
metadata	Optional object.

PowerShell example:

$body = @{
  persona = "hermes"
  source_type = "agent"
  source_name = "Hermes Agent"
  source_id = "agent-hermes-local"
  kind = "markdown"
  theme = "report"
  title = "Morning Brief"
  content = "# Morning Brief`n`n- Review overnight output`n- Plan next actions"
  tags = @("brief", "daily")
  source_prompt = "Prepare a concise morning brief."
  metadata = @{
    model = "gpt-5.5"
    run_id = "brief-001"
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8001/api/artifacts" `
  -Method Post `
  -Headers @{ Authorization = "Bearer dev-token" } `
  -ContentType "application/json" `
  -Body $body

Response shape:

{
  "id": "a1b2c3d4",
  "url": "http://127.0.0.1:8001/a/a1b2c3d4",
  "api_url": "http://127.0.0.1:8001/api/artifacts/a1b2c3d4",
  "raw_url": "http://127.0.0.1:8001/a/a1b2c3d4?raw=1",
  "raw_available": true,
  "persona": "hermes",
  "title": "Morning Brief",
  "kind": "markdown",
  "theme": "report",
  "day": "2026-06-10",
  "created_at": "2026-06-10T15:00:00+00:00",
  "tags": ["brief", "daily"],
  "source_prompt": "Prepare a concise morning brief.",
  "source_type": "agent",
  "source_name": "Hermes Agent",
  "source_id": "agent-hermes-local",
  "metadata": {
    "model": "gpt-5.5",
    "run_id": "brief-001"
  }
}

Create File Artifact

Endpoint:

POST /api/artifacts
Content-Type: multipart/form-data
Authorization: Bearer dev-token

Required fields:

Field	Notes
persona	Required.
title	Required.
file	Required file part.

File kind is inferred from content type:

Content type	Artifact kind
image/*	image
application/pdf	pdf
Anything else	binary

PowerShell/curl example:

curl.exe -X POST "http://127.0.0.1:8001/api/artifacts" `
  -H "Authorization: Bearer dev-token" `
  -F "persona=orion" `
  -F "source_type=agent" `
  -F "source_name=Orion Agent" `
  -F "title=Architecture Diagram" `
  -F "tags=diagram,architecture" `
  -F "file=@C:\path\to\diagram.svg;type=image/svg+xml"

List Artifacts

Endpoint:

GET /api/artifacts

Supported filters:

Query param	Meaning
persona	Exact persona match.
day	Exact day, YYYY-MM-DD.
tag	Matches artifacts containing the tag.
kind	Exact artifact kind.
q	Case-insensitive title fragment.

Examples:

Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?persona=hermes"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?kind=markdown&q=brief"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?day=2026-06-10&tag=daily"

Get Artifact Metadata

Endpoint:

GET /api/artifacts/{id}

Example:

Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts/a1b2c3d4"

Update Artifact Metadata

Endpoint:

PATCH /api/artifacts/{id}
Content-Type: application/json
Authorization: Bearer dev-token

Editable fields:

Field	Notes
title	Must not be blank.
tags	Array or comma-separated string.
source_prompt	String.
source_type	agent, person, or system.
source_name	String.
source_id	String.
metadata	Object. Replaces existing metadata.

Not editable yet:

Field	Reason
content	Content replacement/revisions are intentionally deferred.
persona	Affects storage layout and feed identity.
kind	Affects renderer and storage behavior.
day	Affects time-ordered feed and storage layout.

PowerShell example:

$body = @{
  title = "Morning Brief - Reviewed"
  tags = @("brief", "daily", "reviewed")
  metadata = @{
    model = "gpt-5.5"
    run_id = "brief-001"
    reviewed = $true
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8001/api/artifacts/a1b2c3d4" `
  -Method Patch `
  -Headers @{ Authorization = "Bearer dev-token" } `
  -ContentType "application/json" `
  -Body $body

Rendered And Raw Content

Rendered browser view:

GET /a/{id}

Raw/source view:

GET /a/{id}?raw=1

Raw currently exists for:

Kind	Raw content
markdown	Preserved .md source.
html_full	Stored HTML file served as text.

If raw content is unavailable, Daybook returns a small HTML fallback page.

Capabilities

Endpoint:

GET /api/capabilities

Example response:

{
  "artifact_kinds": ["html_fragment", "html_full", "markdown", "deck", "image", "pdf", "binary"],
  "filters": ["persona", "day", "tag", "kind", "q"],
  "views": ["rendered", "raw"],
  "raw_supported_for": ["markdown", "html_full"],
  "source_types": ["agent", "person", "system"],
  "auth": "bearer_token"
}

Agents should call this endpoint if they need to adapt to the current Daybook instance.

Current MVP Constraints

• A single shared ingest token is used: dev-token.
• Reader/browser authentication is not implemented.
• Content modification/revisions are deferred.
• Office document conversion is not implemented.
• Manual browser upload/drag-and-drop is deferred.
• Pagination/cursors are not implemented yet.