# Blocks API – Tiempo > Time off, closures, maintenance, lunch. A block targets a resource, a location, or the whole business, for a period or for whole local dates. Source: https://tiempo.one/docs/blocks Time off, closures, maintenance, lunch. A block targets a resource, a location, or the whole business, for a period or for whole local dates. ## Create a block `POST /v1/blocks` Makes time unavailable. Give start and end instants, or start_date and end_date for whole local days. With no resource or location it closes the whole business. Send the business’s id in `Tiempo-Account`. ### Body parameters - `resource` (string) A resource id. - `location` (string) A location id. - `start` (timestamp) An ISO-8601 instant. - `end` (timestamp) An ISO-8601 instant, after start. - `start_date` (date) First local date, inclusive. - `end_date` (date) Last local date, inclusive. - `quantity` (integer) Units of capacity to take. Defaults to 1 (for blocks, the whole capacity). - `reason` (string) Your note, kept on the object and its webhook. - `metadata` (map) Up to 50 keys of your own (strings, keys up to 40 characters, values up to 500). Returned on every read and webhook. On update, an empty string removes a key. POST /v1/blocks ```bash curl -X POST "https://api.tiempo.one/v1/blocks" \ -H "Authorization: Bearer tpt_4qZ8m1VwXc0L…" \ -H "Tiempo-Account: acct_01m42yt93ayvyrwr3yczhv6yhw" \ -H "Content-Type: application/json" \ -d '{ "resource": "res_ann", "start": "2026-11-16T13:00:00Z", "end": "2026-11-16T14:00:00Z", "reason": "lunch" }' ``` 200Response ```json { "id": "blk_01m4h3m8x2v6c9z1t4q7w3e5r8", "object": "block", "livemode": false, "resource": "res_01m42ytc9b53589z4rp11zedjy", "location": null, "start": "2026-11-16T13:00:00Z", "end": "2026-11-16T14:00:00Z", "quantity": 1, "reason": "lunch", "metadata": {}, "created_at": "2026-10-04T08:01:00Z" } ``` ## List blocks `GET /v1/blocks` Send the business’s id in `Tiempo-Account`. ### Query parameters - `resource` (string) Only those involving this resource. On the calendar, repeat it for several. - `location` (string) Only those at this location. - `account_wide` (boolean) true for blocks that close the whole business. - `from` (timestamp) Only those ending after this instant. - `to` (timestamp) Only those starting before this instant. - `limit` (integer) 1 to 100. Defaults to 20. - `starting_after` (string) An object id from the previous page; returns the page after it. - `ending_before` (string) An object id; returns the page before it. - `metadata[key]` (string) Only objects whose metadata has this key and value. Repeat for several. GET /v1/blocks ```bash curl "https://api.tiempo.one/v1/blocks?resource=res_ann&from=2026-11-16T00:00:00Z" \ -H "Authorization: Bearer tpt_4qZ8m1VwXc0L…" \ -H "Tiempo-Account: acct_01m42yt93ayvyrwr3yczhv6yhw" ``` 200Response ```json { "object": "list", "data": [ { "id": "blk_01m4h3m8x2v6c9z1t4q7w3e5r8", "object": "block", "livemode": false, "resource": "res_01m42ytc9b53589z4rp11zedjy", "location": null, "start": "2026-11-16T13:00:00Z", "end": "2026-11-16T14:00:00Z", "quantity": 1, "reason": "lunch", "metadata": {}, "created_at": "2026-10-04T08:01:00Z" } ], "has_more": false } ``` ## Retrieve a block `GET /v1/blocks/{id}` Send the business’s id in `Tiempo-Account`. ### Path parameters - `id` (string, required) The object’s id. GET /v1/blocks/{id} ```bash curl "https://api.tiempo.one/v1/blocks/blk_01m4h3m8x2v6c9z1t4q7w3e5r8" \ -H "Authorization: Bearer tpt_4qZ8m1VwXc0L…" \ -H "Tiempo-Account: acct_01m42yt93ayvyrwr3yczhv6yhw" ``` 200Response ```json { "id": "blk_01m4h3m8x2v6c9z1t4q7w3e5r8", "object": "block", "livemode": false, "resource": "res_01m42ytc9b53589z4rp11zedjy", "location": null, "start": "2026-11-16T13:00:00Z", "end": "2026-11-16T14:00:00Z", "quantity": 1, "reason": "lunch", "metadata": {}, "created_at": "2026-10-04T08:01:00Z" } ``` ## Update a block `POST /v1/blocks/{id}` Send the business’s id in `Tiempo-Account`. ### Path parameters - `id` (string, required) The object’s id. ### Body parameters - `start` (timestamp) An ISO-8601 instant. - `end` (timestamp) An ISO-8601 instant, after start. - `start_date` (date) First local date, inclusive. - `end_date` (date) Last local date, inclusive. - `quantity` (integer) Units of capacity to take. Defaults to 1 (for blocks, the whole capacity). - `reason` (string) Your note, kept on the object and its webhook. - `metadata` (map) Up to 50 keys of your own (strings, keys up to 40 characters, values up to 500). Returned on every read and webhook. On update, an empty string removes a key. POST /v1/blocks/{id} ```bash curl -X POST "https://api.tiempo.one/v1/blocks/blk_01m4h3m8x2v6c9z1t4q7w3e5r8" \ -H "Authorization: Bearer tpt_4qZ8m1VwXc0L…" \ -H "Tiempo-Account: acct_01m42yt93ayvyrwr3yczhv6yhw" \ -H "Content-Type: application/json" \ -d '{ "end": "2026-11-16T14:30:00Z" }' ``` 200Response ```json { "id": "blk_01m4h3m8x2v6c9z1t4q7w3e5r8", "object": "block", "livemode": false, "resource": "res_01m42ytc9b53589z4rp11zedjy", "location": null, "start": "2026-11-16T13:00:00Z", "end": "2026-11-16T14:00:00Z", "quantity": 1, "reason": "lunch", "metadata": {}, "created_at": "2026-10-04T08:01:00Z" } ``` ## Delete a block `DELETE /v1/blocks/{id}` Send the business’s id in `Tiempo-Account`. ### Path parameters - `id` (string, required) The object’s id. DELETE /v1/blocks/{id} ```bash curl -X DELETE "https://api.tiempo.one/v1/blocks/blk_01m4h3m8x2v6c9z1t4q7w3e5r8" \ -H "Authorization: Bearer tpt_4qZ8m1VwXc0L…" \ -H "Tiempo-Account: acct_01m42yt93ayvyrwr3yczhv6yhw" ``` 200Response ```json { "id": "…", "object": "…", "deleted": true } ``` The machine-readable description is at [/openapi.json](https://tiempo.one/openapi.json). Try calls in [Swagger UI](https://tiempo.one/swagger-ui.html).[Tiempo home](https://tiempo.one/)[Dashboard](https://tiempo.one/app)