stable · api · 0.1.0

Create a File Object upload grant

POST /api/v1/file-objects/upload-grants

Capability Domain: Files Media

Authentication

projectCredential (files:write)

Scope: files:write

Parameters and request body

Idempotency-Key — header, required
Idempotency-Key schema
```
{
    "type": "string",
    "maxLength": 120
}
```
X-Correlation-ID — header, optional
X-Correlation-ID schema
```
{
    "type": "string",
    "format": "uuid"
}
```

Request schema

application/json

application/json request schema

{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "expected_sha256",
        "expected_content_type",
        "maximum_bytes"
    ],
    "properties": {
        "expected_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
        },
        "expected_content_type": {
            "type": "string",
            "maxLength": 120,
            "enum": [
                "application/pdf",
                "image/gif",
                "image/jpeg",
                "image/png",
                "text/plain"
            ]
        },
        "maximum_bytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1073741824
        }
    }
}

application/json request example

{
    "expected_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "expected_content_type": "image/png",
    "maximum_bytes": 1048576
}

Responses and errors

Status	Description
`200`	Single-use upload grant
`401`	Invalid or revoked Project Credential
`403`	Project Credential lacks the required scope
`422`	Request violates the public contract

200 schema

200 response schema

{
    "type": "object",
    "required": [
        "data"
    ],
    "properties": {
        "data": {
            "type": "object",
            "required": [
                "file_object_id",
                "upload_token",
                "expires_at"
            ],
            "properties": {
                "file_object_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "upload_token": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time"
                }
            }
        }
    }
}

401 schema

401 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

403 schema

403 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

422 schema

422 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

200 example

200 response example

{
    "data": {
        "file_object_id": "50000000-0000-4000-8000-000000000005",
        "upload_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "expires_at": "2026-07-30T10:00:00Z"
    }
}

Idempotency

Requires a unique Idempotency-Key. The upload token is returned only once; reuse is rejected.