Availability

Declare an unavailability

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

POST

/api/v1/availability/unavailabilities

curl https://app.filmo.io/api/v1/availability/unavailabilities \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
  --header 'Content-Type: application/json' \
  --data '{
  "resourceType": "staff",
  "resourceId": "stf_ana",
  "startDate": "2026-08-01T00:00:00+02:00",
  "endDate": "2026-08-15T23:59:59+02:00",
  "state": "unavailable",
  "absenceType": "vacation"
}'

Node.jsfetch('https://app.filmo.io/api/v1/availability/unavailabilities', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ resourceType: 'staff', resourceId: 'stf_ana', startDate: '2026-08-01T00:00:00+02:00', endDate: '2026-08-15T23:59:59+02:00', state: 'unavailable', absenceType: 'vacation' }) })Pythonimport uuid import requests requests.post( "https://app.filmo.io/api/v1/availability/unavailabilities", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "resourceType": "staff", "resourceId": "stf_ana", "startDate": "2026-08-01T00:00:00+02:00", "endDate": "2026-08-15T23:59:59+02:00", "state": "unavailable", "absenceType": "vacation" } )

{
  "data": {
    "availability": {
      "id": "availability_9f3a2b",
      "resourceType": "Example resource type",
      "resourceId": "resource_9f3a2b",
      "resourceName": "Example resource name",
      "startDate": "2026-09-01T08:00:00.000Z",
      "endDate": "2026-09-01T08:00:00.000Z",
      "state": "Madrid",
      "absenceType": "Example absence type",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    },
    "warningCount": 1
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "availability:write"
}

{
  "type": "https://docs.filmo.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Resource not found",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/idempotency_key_reused",
  "title": "Idempotency-Key reused",
  "status": 422,
  "code": "idempotency_key_reused",
  "detail": "The Idempotency-Key header was already used with a different body",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/service_unavailable",
  "title": "Service unavailable",
  "status": 503,
  "code": "service_unavailable",
  "detail": "This feature is not available for the account right now",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

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.

Authorizations

Bearer API key with the scope below. availability:write

Headers

Idempotency-Keystring

Unique identifier of the request, chosen by the client (a UUID works). Between 1 and 255 characters: an empty header is rejected with 400 validation_error, because the client would believe itself protected. Repeating the same key with the SAME body within 24 h returns the stored response without executing again, with the Idempotent-Replay: true header. With a DIFFERENT body it returns 422. It is the safe way to retry after a network timeout.

Limits: min length 1, max length 255

Example:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

Body

application/json

Body schema: UnavailabilityCreateBody

resourceTypestringRequired

Which resource is declared unavailable.

Available options: staff, vehicle, space

resourceIdstringRequired

Identifier of that resource.

Limits: min length 1

startDatestring<date-time>Required

Start, in ISO 8601 with offset.

endDatestring<date-time>Required

End, in ISO 8601 with offset.

statestringRequired

What is declared for that window.

Available options: available, unavailable, unknown

absenceTypestring

Absence type.

Available options: vacation, sick, personal, training, maintenance, inspection, repair, reserved, academic, event, closure, other

reasonstring

Reason. Stored in Filmo and NOT returned by the API.

Limits: max length 500

Response

application/json

Successful response.

Response schema: UnavailabilityResultDto

Envelope: UnavailabilityResultResponse. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay

dataobject

Result of declaring or updating an unavailability.

Show child attributes

data.availabilityobject

The unavailability as it now stands.

Show child attributes

data.availability.idstring

Unique identifier of the unavailability.

data.availability.resourceTypestring

Which resource: staff, vehicle or space.

data.availability.resourceIdstring

Identifier of that resource.

data.availability.resourceNamestring | null

Resource name; null if not recorded.

data.availability.startDatestring<date-time>

Start of the unavailability in ISO 8601 UTC.

data.availability.endDatestring<date-time>

End of the unavailability in ISO 8601 UTC.

data.availability.statestring

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.

data.availability.absenceTypestring | null

Absence type. Only emitted for vehicles and spaces, where it is operational; for staff it is health data and is returned as null.

data.availability.updatedAtstring<date-time> | null

Last modification in ISO 8601 UTC; null if not recorded.

data.warningCountinteger

Commitments of the resource that overlap this unavailability.

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

Status	Codes	Meaning
400	`validation_error`	Malformed query or body. `errors[]` lists every offending field with its stable code.
404	`not_found`	It does not exist or is outside the scope of the API key.
409	`conflict`	The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation.
422	`idempotency_key_reused`	The same key was used before with a different body. Change the key.
503	`service_unavailable`	The feature this operation writes to is switched off for the account. The request is correct; it works again once the feature is switched on.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy

Was this page helpful?

Request examples

Authorizations

Headers

Body

Response

Errors

Deprecation

Related