Refine AgentFeed UI and local workflow
This commit is contained in:
parent
3179f832fc
commit
ba9f5eb168
29 changed files with 2986 additions and 69 deletions
332
docs/api.md
Normal file
332
docs/api.md
Normal file
|
|
@ -0,0 +1,332 @@
|
|||
# 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:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:8001
|
||||
```
|
||||
|
||||
Authentication for write endpoints:
|
||||
|
||||
```http
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```http
|
||||
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:
|
||||
|
||||
```powershell
|
||||
$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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```http
|
||||
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:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```http
|
||||
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:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```http
|
||||
GET /api/artifacts/{id}
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts/a1b2c3d4"
|
||||
```
|
||||
|
||||
## Update Artifact Metadata
|
||||
|
||||
Endpoint:
|
||||
|
||||
```http
|
||||
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:
|
||||
|
||||
```powershell
|
||||
$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:
|
||||
|
||||
```http
|
||||
GET /a/{id}
|
||||
```
|
||||
|
||||
Raw/source view:
|
||||
|
||||
```http
|
||||
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:
|
||||
|
||||
```http
|
||||
GET /api/capabilities
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue