Barzaman access tokens and API

To use Barzaman from a script, Claude Code or another MCP client, create a personal access token. ChatGPT and Claude don’t need one; they connect with secure OAuth sign-in.

Creating a token

1. Open Settings → Account → Sign-in & security → Bots & integrations → Access tokens and tap New token.
2. Give it a name (e.g. “report script”) and choose Read or Read & write.
3. Choose an expiry between 7 and 365 days; every token must expire.
4. The token, starting with bzp_, is shown once. Store it somewhere safe.

Claude Code and MCP clients

The MCP server URL is https://mcp.barzaman.ir/mcp. In Claude Code:

claude mcp add --transport http barzaman https://mcp.barzaman.ir/mcp

If a client doesn’t support OAuth sign-in, send the header Authorization: Bearer bzp_… with your token.

REST API

The base URL is https://api.barzaman.ir/v1/integrations, and every request needs Authorization: Bearer bzp_….

Request	What it does
GET /today	Today summary
GET /items?range=today	List items; range is today, tomorrow, week, overdue or custom (with from and to)
GET /items/search?q=…	Search
POST /items with {"text": "..."}	Create an item from a plain sentence
POST /items/{id}/complete	Complete
POST /items/{id}/snooze	Snooze

Example:

curl -H "Authorization: Bearer bzp_…" https://api.barzaman.ir/v1/integrations/today

Security

• Tokens are stored hashed and never shown again; the list shows when each was last used.
• Grant the least access needed: a script that only reads reports is fine with Read.
• Revoke any token you no longer need or that may have leaked; it stops working immediately.