Scarica app
Scarica
FunzionalitàPrezziBusiness
Scarica app
Scadenzario API · v1

Your deadlines, inside your flows

The REST API creates, reads, updates, completes and pays personal deadlines from scripts and automations. Same key as MCP, same plan quota, personal deadlines only.

Get the keyOpenAPI specGuida italiana
Server-to-serverCloud account requiredNo PRO needed
First call in 3 steps
  1. 1
    Generate the key

    In the app, under Settings → Analyze with AI.

  2. 2
    Test the key

    Call GET /me with the Bearer token.

  3. 3
    Create a deadline

    Find it in the app through sync.

01

Basics

What the Scadenzario API is

An HTTP JSON interface at https://www.scadenzario.app/api/v1 for managing personal deadlines: list, create, update, complete, mark as paid and delete. Built for programs, not browsers: it sets no CORS, so the token must never live in a web page.

Paid and completed stay distinct.

Paying never completes and completing never pays. Paying one instalment of a recurring deadline never closes the series; completing or moving a recurring deadline happens in the app only.

02

Authentication

One key for API and MCP

  1. 1

    Open Settings in Scadenzario.

  2. 2

    Open Analyze with AI.

  3. 3

    Choose API and MCP access key.

  4. 4

    Tap Generate and copy it now: it is shown once only.

Every request carries Authorization: Bearer <key>. Never put the key in the URL: it would land in logs.

Check the keycurl -H "Authorization: Bearer $SCADENZARIO_TOKEN" https://www.scadenzario.app/api/v1/me
03

Reference

Endpoints

All examples use $SCADENZARIO_TOKEN as the environment variable holding the key.

List deadlines

curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  "https://www.scadenzario.app/api/v1/deadlines?status=active&limit=50"

Filters: status=active|completed|all, from, to, q, repeatable label_id (OR), paid, recurring, overdue. Paged answer: {data, next_cursor, truncated}.

curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  "https://www.scadenzario.app/api/v1/deadlines/abc123"

Create a deadline

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: insurance-2026" \
  -d '{ "title": "Car insurance", "due_at": "2026-11-15", "amount": 120.50, "transaction_type": "expense" }' \
  https://www.scadenzario.app/api/v1/deadlines

201 with a Location header. Retrying with the same Idempotency-Key returns the original deadline, no duplicates.

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "deadlines": [ {"title": "Tax", "due_at": "2026-11-15"}, {"title": "Insurance", "due_at": "2026-12-01"} ] }' \
  https://www.scadenzario.app/api/v1/deadlines/batch

Up to 20 deadlines per call; the answer lists created and failed.

Update a deadline

curl -X PATCH -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Car insurance 2026", "amount": 125.00 }' \
  https://www.scadenzario.app/api/v1/deadlines/abc123

On recurring deadlines only metadata (title, notes, amount, payment, labels): the date moves in the app.

Complete and reopen

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/deadlines/abc123/complete
curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/deadlines/abc123/reopen

One-shot deadlines only, never recurring ones. Reopening re-checks the plan quota.

Pay without completing

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "paid_at": "2026-10-10T10:00:00Z", "amount": 120.50 }' \
  https://www.scadenzario.app/api/v1/deadlines/abc123/pay
curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/deadlines/abc123/unpay

Works on recurring deadlines too: paying one instalment never closes the series. Paid deadlines stop sending email reminders.

Delete a deadline

curl -X DELETE -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/deadlines/abc123

204 answer. Writes the sync tombstone: the deadline drops from every device. On a recurring deadline it ends the series.

Labels and summary

curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/labels
curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Car" }' \
  https://www.scadenzario.app/api/v1/labels
curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/summary

/summary answers with overdue, next 7 and 30 days, and the unpaid total: the "how much do I owe this month?" question.

04

Long lists

Cursor pagination

GET /deadlines returns at most limit items (default 50, max 200). When next_cursor is not null there are more pages: repeat the same request with&cursor=.... When truncated is true the scan hit its internal cap: keep going with next_cursor so nothing is lost.

curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  "https://www.scadenzario.app/api/v1/deadlines?limit=200&cursor=eyJkdWVBdE1pbGxpcyI6MTc5MjAwMDAwMDAwMCwiaWQiOiJhYmMifQ"
05

Diagnostics

Errors

Body is always {error: {code, message}}. Full detail in openapi.json.

401 unauthenticated

Missing or invalid key. Carries WWW-Authenticate: Bearer.

400 invalid_input

Malformed JSON, invalid field, unreadable cursor.

404 not_found

Unknown or deleted id.

409 unsupported_for_recurring

Operation forbidden on recurring deadlines: do it in the app.

409 sync_limit_reached

Plan quota exhausted, with details: {count, limit}.

429 rate_limited

Too many requests, with a Retry-After header.

06

Quotas

Limits

  • 60 requests per minute per account, then 429;
  • 256 KB max body;
  • plan cloud quota: 20 active deadlines on Free, 5,000 on PRO — enforced inside every write;
  • personal deadlines only, no teams in v1;
  • attachments stay in the app: the API only reports whether they exist.
07

Automations

Using it from n8n and Make

n8n — HTTP Request node

  1. 1

    Add an HTTP Request node, POST method, URL https://www.scadenzario.app/api/v1/deadlines.

  2. 2

    Under Authentication pick Generic Credential Type → HttpHeaderAuth: name Authorization, value Bearer <key>.

  3. 3

    JSON body with title and due_at. Add an Idempotency-Key header with a stable ID when the flow can re-run.

Make — HTTP module

  1. 1

    Add the HTTP → Make a request module, POST method, URL https://www.scadenzario.app/api/v1/deadlines.

  2. 2

    In Headers add Authorization: Bearer <key> and Content-Type: application/json.

  3. 3

    Body with ISO title and due_at.

08

Recipe

Create a deadline from a new spreadsheet row

Typical case: a Google Sheet collects bills to pay. In n8n theGoogle Sheets Trigger → Row Added trigger feeds an HTTP Request node toPOST /deadlines with a body built from the columns:

{
  "title": "Invoice {{ $json.Supplier - {$json.Number} }}",
  "due_at": "{{ $json.Due }}",
  "amount": "{{ $json.Amount }}",
  "transaction_type": "expense",
  "client_request_id": "bills-sheet-{{ $json.ID }}"
}

A stable client_request_id on the row ID makes the flow re-runnable without duplicates. Permanent two-way sync needs the external-ID upsert (after v1).

09

FAQ

Frequently asked questions

Do I need PRO to use the API?

No. The same rule as MCP applies: the API is available on every plan within the cloud quota (20 active deadlines on Free, 5,000 on PRO). PRO stays worthwhile for quota, teams and future features.

API or MCP, which one?

MCP when an AI assistant does the work (Claude, Codex, Cursor). API when a program does it: scripts, n8n, Make, back-office tools. Same token, same operations, same quota.

Can I read or change team deadlines?

No: v1 covers personal deadlines only. Shared team deadlines stay out until a Business customer uses them through the API.

Why cannot I complete a recurring deadline?

Completing one also creates the next occurrence under the app rules (series end, monthly days, custom dates). Moving that flow server-side without divergence is dedicated work: planned as API v1.1, only if API users ask for it. Paying one instalment already works.

How do I avoid duplicates when syncing a back-office tool?

Today with the Idempotency-Key header on retried requests. A permanent external-ID link (upsert) comes after v1, with the first real tool to sync.

Where do API-created deadlines show up?

In the app through normal sync: they land on the phone and schedule notifications like hand-made ones.

Prefer an AI assistant?

Same key, MCP protocol for Claude and Codex.

The MCP guide explains the assistant connection.

MCP guide