Availability

Correct or close an unavailability

With action: "edit" it corrects the dates or the type; with action: "finish_now" it closes it at this instant, which is the "came back early" case.

PATCH

/api/v1/availability/unavailabilities/{unavailabilityId}

curl https://app.filmo.io/api/v1/availability/unavailabilities/unav_8f2a1c \
  --request PATCH \
  --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 '{
  "action": "finish_now",
  "expectedUpdatedAt": "2026-07-20T10:12:31+02:00"
}'

Node.jsfetch('https://app.filmo.io/api/v1/availability/unavailabilities/unav_8f2a1c', { method: 'PATCH', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ action: 'finish_now', expectedUpdatedAt: '2026-07-20T10:12:31+02:00' }) })Pythonimport uuid import requests requests.patch( "https://app.filmo.io/api/v1/availability/unavailabilities/unav_8f2a1c", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "action": "finish_now", "expectedUpdatedAt": "2026-07-20T10:12:31+02:00" } )

{
  "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

expectedUpdatedAt is the optimistic lock: copy it from the read and, if someone touched it in the meantime, the request is rejected with 409 conflict and nothing is written; read it again and retry. edit only applies to a manual unavailability that has not started yet: one created by a task or by a schedule is changed from its source, and one already started can only be closed; both respond 409. Its new start has to be later than now and its end after its start (400 validation_error with errors[0].path on the field, as with an absenceType of another resource type), and on a space the new window cannot fall on its bookings (409). finish_now only closes an unavailability in progress —unavailable, already started and not yet ended—, also one that comes from a schedule; any other responds 409, and so does one created by a task. warningCount is always 0 here: overlapping commitments are counted when the unavailability is declared. 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"

Path parameters

unavailabilityIdstringRequired

Unavailability identifier.

Limits: min length 1

Body

application/json

Body schema: UnavailabilityUpdateBody

actionstringRequired

"edit" corrects the unavailability; "finish_now" closes it right now.

Available options: edit, finish_now

expectedUpdatedAtstring<date-time>Required

Last modification date you read. If it does not match, the request is rejected.

startDatestring<date-time>

New start.

endDatestring<date-time>

New end.

absenceTypestring | null

New absence type; null clears it.

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

reasonstring | null

New reason; null clears it. 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

Path parameters

Body

Response

Errors

Deprecation

Related