Location

Get a ticket to attach a file to a location

Changed on

A write key and its PIN that may change the element (the write rule of PATCH; an agent seat answers as its sponsor). Body: the file's name, kind and size, and an optional label. Returns a single-use ticket in the image lane's shape with kind file: send the bytes to upload_url with it. The file is listed once the upload host has checked and stored it. Kinds: text (txt, md, json, csv, yaml, toml), pdf, and zip only as a world's own bundle. At most 25 MB a file; a world holds 250 MB of files; 200 tickets a world a day. This route takes no Idempotency-Key: the single-use ticket is the idempotency (a second POST is a second ticket). Files on elements answer only where the server has them switched on; elsewhere every files route is a 404.

post/api/v2/location/{id}/files

Request

  • Base URL: https://www.onlyworlds.com
  • URL: https://www.onlyworlds.com/api/v2/location/{id}/files
  • Auth: API key in header API-Key and API key in header API-Pin

Path parameters

idstring uuid required

The location's id (a malformed id is a 422).

Headers

X-OW-Agentstring

Send it (any non-empty value) when an agent makes this write: the change is recorded with changed_via declared (a delete's tombstone with deleted_via). An agent seat's key and MCP are recorded as agent-made without it. The value is never stored.

Request body

namestring required

The file's name, ending in its kind's extension (.yml and .markdown are taken too).

kind'pdf' | 'txt' | 'md' | 'json' | 'csv' | 'yaml' | 'toml' | 'zip' required
sizeinteger required

Bytes.

labelstring nullable

Response

A ticket for one file upload. Cache-Control: no-store.

ticketstring required

Opaque to clients: send it to upload_url as Authorization: Bearer <ticket>, the file's raw bytes as the body.

upload_urlstring required
prefixstring required

w/<world_id>/<element_id>/

keystring required

The object key the file lands under.

max_bytesinteger required

The most this ticket accepts: 25 MB, or what the world has left, whichever is smaller.

expinteger required

Unix seconds after which the ticket is refused (10 minutes).

uses1 required
kind'file' required
file_idstring uuid required

Changes

  • 4dd5b1cd0687Revision changes
    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new character_taken enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status

    • warning

      added the new world_full enum value to the / response property for the response status