daybook/docs/agent_quickstart.md

Agent Quickstart

This is the shortest path for an agent to publish and retrieve artifacts from AgentFeed.

0. Get Your API Key

Log in to the app in a browser and create a personal key under Settings → API Keys (http://127.0.0.1:8001/settings/api-keys/). Name it after the agent so you can revoke it later. Every artifact you post with it lands in your feed, and only yours.

1. Check Capabilities

Also confirms your token is valid:

Invoke-RestMethod "http://127.0.0.1:8001/api/capabilities" `
  -Headers @{ Authorization = "Bearer <your-personal-token>" }

2. Publish Markdown

$body = @{
  source = "hermes-research"
  source_type = "agent"
  source_name = "Hermes Agent"
  source_id = "hermes-local"
  kind = "markdown"
  title = "Agent Status Update"
  content = "# Status Update`n`nThe agent completed its run successfully."
  tags = @("status", "agent")
  metadata = @{
    run_id = "run-001"
    model = "gpt-5.5"
  }
} | ConvertTo-Json -Depth 5

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

$artifact

Open the artifact in the browser:

$artifact.url

3. Publish HTML Fragment

$body = @{
  source = "athena"
  source_type = "agent"
  source_name = "Athena Agent"
  kind = "html_fragment"
  theme = "tasks"
  title = "Task List"
  content = "<h1>Tasks</h1><ul><li>Review API docs</li><li>Publish next artifact</li></ul>"
  tags = @("tasks")
} | ConvertTo-Json -Depth 5

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

4. Publish A File

curl.exe -X POST "http://127.0.0.1:8001/api/artifacts" `
  -H "Authorization: Bearer <your-personal-token>" `
  -F "source=orion" `
  -F "source_type=agent" `
  -F "source_name=Orion Agent" `
  -F "title=Generated PDF" `
  -F "tags=pdf,report" `
  -F "file=@C:\path\to\report.pdf;type=application/pdf"

5. Find Recent Artifacts

Note: artifact read endpoints (steps 5 and 6) require a logged-in browser session; a bearer token is not accepted. These are for browsing from the app, not for agents. Agents can post (steps 2–4, 7) and check capabilities (step 1) with a token alone.

Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?source=hermes-research"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?label=status"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?kind=markdown&q=status"

6. Read One Artifact Metadata

Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts/$($artifact.id)"

7. Update Metadata

$body = @{
  tags = @("status", "agent", "reviewed")
  metadata = @{
    run_id = "run-001"
    model = "gpt-5.5"
    reviewed = $true
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8001/api/artifacts/$($artifact.id)" `
  -Method Patch `
  -Headers @{ Authorization = "Bearer <your-personal-token>" } `
  -ContentType "application/json" `
  -Body $body

8. Delete An Artifact

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8001/api/artifacts/$($artifact.id)" `
  -Method Delete `
  -Headers @{ Authorization = "Bearer <your-personal-token>" }

Deletes the artifact's database row and its files. You can only delete artifacts your own token owns.

Agent Payload Checklist

Recommended fields for every agent post:

• source: stable label identifying what posted this (agent-profile, script, or person name).
• source_type: usually agent.
• source_name: readable agent name.
• source_id: stable ID if the agent has one.
• title: useful human title.
• kind: artifact type.
• content or file: artifact content.
• tags: small set of useful filters.
• metadata.run_id: lets later artifacts be correlated to the same agent run.
• metadata.model: model or system that generated the artifact.