OpenAPI Specification
openapi: 3.0.0
info:
title: SpAItial Developer files API
description: Programmatic API for generating 3D worlds. See the [Getting Started guide](https://docs.spaitial.ai/api/getting-started) for authentication and usage examples.
version: 1.0.0
contact: {}
servers:
- url: https://api.spaitial.ai
description: Production
tags:
- name: files
description: File upload endpoints
paths:
/v1/files:
get:
operationId: V1Files_listFiles
parameters:
- name: offset
required: false
in: query
description: Number of files to skip before returning results.
schema:
type: integer
minimum: 0
default: 0
- name: limit
required: false
in: query
description: Maximum number of files to return.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
'200':
description: Paginated file list
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
files:
type: array
items:
type: object
properties:
file_id:
type: string
content_type:
type: string
file_size:
type: number
exclusiveMinimum: 0
expires_at:
type: string
created_at:
type: string
consumed_at:
anyOf:
- type: string
- type: 'null'
status:
type: string
enum:
- available
- consumed
- expired
required:
- file_id
- content_type
- file_size
- expires_at
- created_at
- consumed_at
- status
additionalProperties: false
limit:
type: integer
minimum: 1
maximum: 100
offset:
type: integer
minimum: 0
maximum: 9007199254740991
has_more:
type: boolean
required:
- files
- limit
- offset
- has_more
additionalProperties: false
'400':
description: Invalid query parameters
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
request_id:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
required:
- code
- message
additionalProperties: false
required:
- error
additionalProperties: false
'401':
description: Unauthorized
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
request_id:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
required:
- code
- message
additionalProperties: false
required:
- error
additionalProperties: false
'403':
description: Forbidden
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
request_id:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
required:
- code
- message
additionalProperties: false
required:
- error
additionalProperties: false
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
request_id:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
required:
- code
- message
additionalProperties: false
required:
- error
additionalProperties: false
security:
- api-key: []
summary: List files uploaded by this API key
tags:
- files
servers:
- url: https://api.spaitial.ai
description: Production
post:
operationId: V1Files_uploadFile
parameters: []
requestBody:
required: true
description: Image file to upload
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: Image file (JPEG, PNG, WebP, GIF, max 100MB)
required:
- file
responses:
'201':
description: File uploaded successfully
'400':
description: Invalid file
'401':
description: Unauthorized
'403':
description: Moderation rejected
'413':
description: File too large
'429':
description: Rate limit exceeded
security:
- api-key: []
summary: Upload a file for later use in world generation
tags:
- files
servers:
- url: https://api.spaitial.ai
description: Production
components:
securitySchemes:
api-key:
scheme: bearer
bearerFormat: API Key
type: http
description: 'API key issued by the developers site. Example: spt_live_abc123...'