*MCP › Reference › Catalog & inventory › Availability*

# Declare an unavailability

> Declares that a resource is not available in a window: holidays, a maintenance, a closure.

`reason` is ACCEPTED and not returned: it stays in Filmo for whoever has access. For a person or a vehicle, overlapping commitments do not block: the unavailability is recorded and `warningCount` says how many already reserved commitments overlap with it. A space is different: declaring it `unavailable` in a window where it is booked responds 409 `conflict` and nothing is written, so on a space `warningCount` is always 0. It also responds 409 if an identical unavailability already exists (same resource, window, state, type and reason). It responds 400 `validation_error`, with `errors[0].path` on the field, when `endDate` is not after `startDate`, when `resourceId` does not exist or belongs to another account, and when `absenceType` is not one of its resource type: `vacation`, `sick`, `personal`, `training` or `other` for staff; `maintenance`, `inspection`, `repair`, `reserved` or `other` for vehicles; `academic`, `maintenance`, `event`, `closure` or `other` for spaces. On a space it responds 503 `service_unavailable` while space unavailabilities are switched off for the account.

TOOL `filmo_unavailabilities_create` · `availability:write` · 120/min

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `resourceType` | string | Yes | Which resource is declared unavailable. `staff`, `vehicle`, `space` |
| `resourceId` | string | Yes | Identifier of that resource. |
| `startDate` | string<date-time> | Yes | Start, in ISO 8601 with offset. |
| `endDate` | string<date-time> | Yes | End, in ISO 8601 with offset. |
| `state` | string | Yes | What is declared for that window. `available`, `unavailable`, `unknown` |
| `absenceType` | string | No | Absence type. `vacation`, `sick`, `personal`, `training`, `maintenance`, `inspection`, `repair`, `reserved`, `academic`, `event`, `closure`, `other` |
| `reason` | string | No | Reason. Stored in Filmo and NOT returned by the API. |
| `idempotencyKey` | string | No | Idempotency key chosen by the client (a UUID is recommended). Repeating the same key with the same arguments within 24 h returns the stored response without executing again; with different arguments it responds 422. It is the safe way to retry after a network failure. |

## Result

On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`.

| Name | Type | Description |
| --- | --- | --- |
| `availability` | object | The unavailability as it now stands. |
| `availability.id` | string | Unique identifier of the unavailability. |
| `availability.resourceType` | string | Which resource: staff, vehicle or space. |
| `availability.resourceId` | string | Identifier of that resource. |
| `availability.resourceName` | string | Resource name; null if not recorded. |
| `availability.startDate` | string<date-time> | Start of the unavailability in ISO 8601 UTC. |
| `availability.endDate` | string<date-time> | End of the unavailability in ISO 8601 UTC. |
| `availability.state` | string | Declared state. This list only returns `unavailable` windows that have not ended yet, so it is always `unavailable` here; `available` and `unknown` exist as declarations but are not listed. |
| `availability.absenceType` | string | Absence type. Only emitted for vehicles and spaces, where it is operational; for staff it is health data and is returned as null. |
| `availability.updatedAt` | string<date-time> | Last modification in ISO 8601 UTC; null if not recorded. |
| `warningCount` | integer | Commitments of the resource that overlap this unavailability. |

*Call · filmo_unavailabilities_create*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_unavailabilities_create",
    "arguments": {
      "resourceType": "staff",
      "resourceId": "reso_8f2a1c",
      "startDate": "2026-09-01T08:00:00Z",
      "endDate": "2026-09-01T08:00:00Z",
      "state": "available"
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": {
      "availability": {
        "id": "id_8f2a1c",
        "resourceType": "<resourceType>",
        "resourceId": "reso_8f2a1c",
        "resourceName": "Example",
        "startDate": "2026-09-01T08:00:00Z",
        "endDate": "2026-09-01T08:00:00Z",
        "state": "<state>",
        "absenceType": "<absenceType>",
        "updatedAt": "2026-09-01T08:00:00Z"
      },
      "warningCount": 1
    },
    "meta": {
      "idempotencyKey": "<the key you sent, or the one the server generated>",
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## The same operation by REST

This tool runs [`POST /api/v1/availability/unavailabilities`](https://docs.filmo.io/rest-api/endpoint-reference/availability/declare-an-unavailability).

---

Canonical URL: https://docs.filmo.io/mcp/tools/availability/filmo-unavailabilities-create  
Last updated: 2026-10-25