Skip to content
Skip to Content
APIQuickstart

Quickstart

From nothing to a todo you created over HTTP.

You need a Doozy account with a workspace, and curl. Five steps, about five minutes. Every step shows what comes back.

1. Create a key

In Doozy, open Settings, then API keys, then Create key.

Give it a name you will recognise later, and choose what it may do. For this walkthrough, pick Full access; for anything real, grant the least that works. Scopes explains what each one opens.

The key appears once, when you create it:

doozy_sk_KFpivWUqE0iq5EhgHGdq70X0VLdhyC2l7Itf8mdk0eJAVI

Copy it now. We store only a hash, so we cannot show it again. If you lose it, revoke it and create another.

Keep it out of your source code. An environment variable is the usual place:

export DOOZY_API_KEY="doozy_sk_..."

2. Check it works

curl https://api.usedoozy.com/api/v1/me \
  -H "Authorization: Bearer $DOOZY_API_KEY"
{
  "object": "identity",
  "workspace": { "id": "7f2a...", "name": "Acme customer success" },
  "user": { "id": "3c8e...", "email": "you@acme.com", "name": "You" },
  "credential": {
    "type": "api_key",
    "name": "Quickstart",
    "scopes": [
      "todos:read", "todos:write",
      "chats:read", "chats:write",
      "agents:read", "agents:write",
      "captures:read", "captures:write"
    ],
    "expiresAt": null
  }
}

That workspace is where every request with this key lands, and scopes is whatever you granted in step 1.

If this fails instead: 401 means the key is wrong, revoked, or was pasted with a line break in it. 403 means the key is fine but was not granted the scope this call needs. Errors has the rest.

3. Read the workspace

curl "https://api.usedoozy.com/api/v1/todos?limit=5" \
  -H "Authorization: Bearer $DOOZY_API_KEY"

Lists come back the same way everywhere: data holds the records, hasMore says whether there are more, and nextCursor is what you pass back to get them.

4. Create a todo

curl -X POST https://api.usedoozy.com/api/v1/todos \
  -H "Authorization: Bearer $DOOZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Review the Q3 numbers",
    "content": "Compare against the forecast and flag anything more than 10 percent out.",
    "priority": "high",
    "dueDate": "2026-09-01"
  }'
{
  "object": "todo",
  "id": "1b4c...",
  "title": "Review the Q3 numbers",
  "status": "ready",
  "priority": "high",
  "dueDate": "2026-09-01",
  "assignees": [],
  "createdAt": "2026-08-20T14:03:11.000Z"
}

Open Doozy and it is there. Keep the id: the next step uses it.

The Idempotency-Key header is worth the habit. If the request times out and you retry with the same key, you get the first response back instead of a second todo. See Errors.

5. Hand it to an agent

This is the part other todo APIs do not have. Find an agent first:

curl https://api.usedoozy.com/api/v1/agents \
  -H "Authorization: Bearer $DOOZY_API_KEY"

Take an agent’s id from data in that list, and the todo id from step 4, and start the work:

curl -X POST https://api.usedoozy.com/api/v1/todos/1b4c.../runs \
  -H "Authorization: Bearer $DOOZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "3c8e..." }'
{
  "object": "todo_run",
  "id": "5d2f...",
  "todoId": "1b4c...",
  "chatId": "8e91...",
  "status": "running",
  "startedAt": "2026-08-20T14:04:02.000Z",
  "finishedAt": null
}

The agent is now working, and this response came back before it finished — that is how every agent operation behaves. chatId is where the work happens: read that chat’s messages to watch it, and its status to know when it is done. Working with agents shows both.

Next

Last updated on
OverviewAuthentication and keys