daybook/docs/agent_quickstart.md

# Agent Quickstart

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

## 0. Get Your API Token

Log in to the app in a browser and copy your personal token from **Settings → Account**
(`http://127.0.0.1:8001/settings/account/`). Every artifact you post with it lands in your
feed, and only yours.

## 1. Check Capabilities

Also confirms your token is valid:

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

## 2. Publish Markdown

```powershell
$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:

```powershell
$artifact.url
```

## 3. Publish HTML Fragment

```powershell
$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

```powershell
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.

```powershell
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

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

## 7. Update Metadata

```powershell
$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
```

## 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.