Connect Dayroom to the tools you use

Your first request

Build with REST: HTTPS, JSON and scoped API tokens.

Set DAYROOM_API_TOKEN securely in your environment, then run:

export DAYROOM_API_URL='https://app.usedayroom.com/api/v1'
curl --fail-with-body "$DAYROOM_API_URL/workspace" \
  --header "Authorization: Bearer $DAYROOM_API_TOKEN"

Example response (IDs and names are illustrative):

{
  "workspace": {"id": "workspace_123", "name": "Acme Studio"},
  "you": {"id": "person_123", "name": "Amara", "owner": false},
  "member_count": 8,
  "can_send": false,
  "app": "Release notifications"
}

Use GET /conversations to find conversation IDs, and GET /people to find person IDs. A token already selects its workspace; you don’t pass a workspace ID in the URL.

Authentication and permissions

Every request uses Authorization: Bearer YOUR_API_TOKEN. Browser cookies, webhook credentials and MCP OAuth tokens cannot authenticate to this API. Keep tokens on your server; browser CORS access is not enabled.

Tokens expire after 7, 30 or 90 days. Up to 20 active tokens can belong to one person. Only a token hash is stored; the secret is shown once. To rotate, create a replacement, update your backend and revoke the old token.

A token acts as its creator in one workspace. It never grants extra access. Private rooms, DMs and to-dos keep their existing permissions; archived rooms stay read-only, deleted rooms disappear, and plan restrictions still apply. Private companion conversations and connected-provider data are excluded.

Revoke access from API tokens. Password changes, account recovery and workspace removal also revoke affected tokens. Rejoining a workspace does not restore them. Revocation prevents new authenticated requests; a request already executing may finish.

Working examples

Read messages with Python

Uses the Python standard library. The conversation ID comes from GET /conversations.

import json
import os
from urllib.parse import quote
from urllib.request import Request, urlopen

base = os.environ["DAYROOM_API_URL"].rstrip("/")
token = os.environ["DAYROOM_API_TOKEN"]
conversation = quote(os.environ["DAYROOM_CONVERSATION_ID"], safe="")
request = Request(
    f"{base}/conversations/{conversation}/messages?limit=20",
    headers={"Authorization": f"Bearer {token}"},
)
with urlopen(request, timeout=20) as response:
    page = json.load(response)
for message in page["messages"]:
    print(message["author"]["name"], message["text"])
print("Older messages cursor:", page["before_message_id"])

Send a message with Node.js

Requires built-in fetch. Choose read and write when creating the token. Persist the same event key and JSON for retries.

const base = process.env.DAYROOM_API_URL.replace(/\/$/, '');
const conversation = encodeURIComponent(process.env.DAYROOM_CONVERSATION_ID);
const response = await fetch(`${base}/conversations/${conversation}/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DAYROOM_API_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'release-2026-11-02-001'
  },
  body: JSON.stringify({text: 'The new release is ready for review.'}),
  signal: AbortSignal.timeout(20000)
});
const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status} ${result.error.code}: ${result.error.message}`);
}
console.log(result.message.id, result.duplicate);

Successful sends return 200, including the first request:

{
  "message": {
    "id": 123,
    "conversation_id": "room_123",
    "author": {"id": "person_123", "name": "Amara"},
    "text": "The new release is ready for review.",
    "created": "2026-11-02T12:00:00Z",
    "thread_root_id": null,
    "thread_reply_count": 0,
    "reply_to": null,
    "files": [],
    "reactions": [],
    "sent_via": "Release notifications",
    "agent": false,
    "webhook": false
  },
  "duplicate": false
}

Reply in a thread

curl --fail-with-body "$DAYROOM_API_URL/conversations/$DAYROOM_CONVERSATION_ID/messages" \
  --header "Authorization: Bearer $DAYROOM_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: release-thread-reply-001' \
  --data '{"text":"Deployment is complete.","thread_root_id":123}'

Create a private to-do

curl --fail-with-body "$DAYROOM_API_URL/todos" \
  --header "Authorization: Bearer $DAYROOM_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: release-followup-task-001' \
  --data '{"title":"Review the release notes","due":"Friday","shared":false}'

Returns {"todo":{...}}. Without assignee_id, the to-do belongs to you. Assigning someone else defaults to team visibility; send shared:false to keep it private between you and the assignee.

Endpoint reference

Base URL: https://app.usedayroom.com/api/v1. Responses are JSON objects, not JSON-RPC. All successful operations return 200. Timestamps are ISO 8601 UTC strings; nullable fields are returned as JSON null.

Download the OpenAPI 3.1 document for request and response schemas. Unknown fields and repeated query parameters are rejected. Omit optional request fields instead of sending null. Send {} for an operation with no body fields.

Response collections

• /people: people, each with id, name, you, owner, online and status.
• /conversations: conversations, each with id, name, kind, topic, unread, mentions, muted, archived and last_message_id.
• Message list: conversation, messages, has_more, before_message_id.
• Single message: conversation and message. Thread: root, replies, has_more, before_message_id.
• Search: results, has_more, before_message_id. Each result includes conversation_name.
• To-do list: todos. Create/update: todo. Each has id, title, status, assignee, due, shared, created, conversation_id and message_id.
• Direct send: conversation_id, message, duplicate. Reaction: message_id, reactions. Mark read: conversation_id, unread.

File metadata may appear in messages. File upload/download, message edits/deletion, room administration, Works project mutations, outbound event subscriptions and provider APIs are outside v1. A Works task returned in to-dos must be edited in Dayroom.

Pagination

Messages are returned oldest first within each page. Search results are newest first. Start with limit=20 (maximum 50). If has_more is true, pass the returned before_message_id on the next request:

GET /api/v1/conversations/room_123/messages?limit=20&before_message_id=123
GET /api/v1/messages/search?query=release&limit=20&before_message_id=123

Treat the returned cursor as opaque: imported history can have a different chronology from numeric IDs. Don’t subtract from it. Threads also accept before_message_id; their page size is set by Dayroom. around_message_id locates a message’s surrounding context and uses a server-sized page; don’t combine it with before_message_id.

People, conversations and to-dos return their currently visible collection without cursors. Reading messages doesn’t mark them read; use PUT /conversations/{id}/read explicitly.

Errors, limits and safe retries

{
  "error": {
    "code": "invalid_token",
    "message": "Use a valid, unexpired Dayroom API token.",
    "request_id": "73a102ab92fe0123456789ab"
  }
}

Every API response includes X-Request-ID. Keep that ID when reporting a failed request; don’t log the bearer token.

Limits are 240 requests per minute per token and 600 per source IP, including invalid authentication attempts. Existing operation limits also apply, such as 100 message-send attempts per minute per person. Tokens are available on every plan; ordinary plan and visibility rules still apply.

Idempotency

Sending messages, sending DMs and creating to-dos require Idempotency-Key: 8–90 ASCII letters, digits, underscores or hyphens. Generate one per logical event. Retry with exactly the same key, endpoint and fields after a timeout, network error or 5xx response.

The key is bound to that token and request. Reusing it with changed fields returns 409. Message retries return the same ID and duplicate:true; to-do retries return the existing to-do. Keys remain bound for the token’s lifetime. Retrying after the created message or to-do was deleted returns 410. Permissions are checked again on retries, so a previously successful request can fail after access changes. Rotating a token starts a separate key namespace; don’t replay completed events with the replacement.

PUT/PATCH operations set the requested state and can be retried with the same body. They may produce a newer result if someone else changed the resource in between. Avoid automatic retries for other 4xx errors.

Versioning

The contract lives under /api/v1. Clients should ignore new response fields. Breaking request or response changes belong in a new API version. The OpenAPI document describes this deployed service; there is no separate sandbox host. Use a dedicated workspace for development.