Endpoints
Create a bounded workspace upload target; this does not run or restore data.
Commands: 30 requests per grant per fixed UTC minute. Buckets are separate for reads and commands. Request bodies are limited to 65,536 bytes. Retry a 429 only after Retry-After; retain the original Idempotency-Key for an unchanged command.
Request
Authentication is required by the published contract.
curl -X POST 'https://ursy.locker/api/v1/rooms/{room}/portable-imports' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_SERVICE_TOKEN'- Scopes
- locker.files.write, locker.rooms.control, locker.backups.write
- Execution
- At the owning service
- Risk classification
- not declared
Parameters
room path · string requiredSee the accepted schema for constraints.
Idempotency-Key header · string requiredSee the accepted schema for constraints.
This operation is documented here. Use the owning service with the appropriate credentials and permissions to execute it.
Response schemas and request body
{
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"template": {
"type": "string",
"description": "Exact pinned target image"
},
"file_bytes": {
"type": "integer",
"minimum": 0,
"maximum": 34359738368
},
"file_count": {
"type": "integer",
"minimum": 0,
"maximum": 4096
}
},
"required": [
"template",
"file_bytes",
"file_count"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Successful query or command receipt",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "object",
"properties": {
"import_id": {
"type": "string"
},
"target_room_id": {
"type": "string"
},
"target_backup_id": {
"type": "string"
},
"archive_key_base64": {
"type": "string"
},
"manifest_metadata": {
"type": "object"
},
"manifest_received_bytes": {
"const": 0
},
"approval_url": {
"type": "string"
},
"quota": {
"type": "integer"
},
"manifest_page_bytes": {
"const": 32768
},
"upload_requires_fresh_authorisation": {
"const": true
}
},
"required": [
"import_id",
"target_room_id",
"target_backup_id",
"archive_key_base64",
"manifest_metadata",
"manifest_received_bytes",
"approval_url",
"quota"
],
"additionalProperties": true
},
"meta": {
"type": "object",
"required": [
"request_id"
],
"properties": {
"request_id": {
"type": "string"
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Read bucket 120; command bucket 30.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this bucket after this request.",
"schema": {
"type": "integer",
"minimum": 0
}
},
"X-RateLimit-Reset": {
"description": "Unix time in seconds at the next minute boundary.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}
},
"400": {
"description": "Invalid input or JSON object; correct the request before retrying",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
},
"401": {
"description": "Missing or invalid resource-bound identity",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
},
"headers": {
"WWW-Authenticate": {
"description": "Bearer challenge linking the Locker protected-resource metadata.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Scope or ownership denied",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
},
"404": {
"description": "Unknown route/method, missing resource or resource unavailable to this actor",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
},
"409": {
"description": "Version, state or idempotency conflict; inspect the error before retrying",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
},
"413": {
"description": "Request exceeds the 65,536-byte body limit; reduce the body",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
},
"415": {
"description": "A non-empty request body must use application/json",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
},
"429": {
"description": "The fixed-minute read or command bucket is exhausted; wait Retry-After seconds",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
},
"headers": {
"Retry-After": {
"description": "Seconds until the limit resets; retry with bounded backoff.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"X-RateLimit-Limit": {
"description": "Read bucket 120; command bucket 30.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this bucket after this request.",
"schema": {
"type": "integer",
"minimum": 0
}
},
"X-RateLimit-Reset": {
"description": "Unix time in seconds at the next minute boundary.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}
},
"503": {
"description": "Required integration unavailable; no success is assumed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
},
"default": {
"description": "Typed service error; obey error.retryable and error.next_action. A response is not proof that an action completed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"next_action": {
"type": [
"object",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
},
"500": {
"description": "Unexpected server fault. The body may not be JSON and no success is assumed; for a command, retry later with the same Idempotency-Key."
}
}
}