Skip to main content
POST
Python SDK

Access

This operation needs a Parable token. An MCP token cannot call it. See Authentication for the kinds of token. Your roles must grant tenant.parables.manage.

Errors

  • WA-AF-020: The file name is empty after cleaning, or longer than 255 bytes. Use a shorter name with its extension, such as logo.svg.
  • WA-AF-003: This operation stores SVG, CSV and JSON Lines text only. Use a file name that ends in .svg, .csv or .jsonl.
  • WA-AF-021: The file is larger than the Workspace file size setting. Store a smaller file.
  • WA-AF-024: The Parable already keeps as many files as its limit allows. Ask Parable staff to raise the limit.
  • PA-AU-001: The Parable is not visible to the caller. Check the rootRefId, or ask for a seat on the Parable.
  • PA-AU-007: The Parable is Pocketed, so its files are read-only. Restore the Parable. Then call again.
  • HTTP 403: The caller can view this Parable but cannot change its files. Ask a person with Primary or Publishing to add the file.
  • HTTP 409: Another person or another Parable used this idempotencyKey, or a call that stopped holds a reservation that expired. Send a new idempotencyKey.
  • HTTP 503: The file could not be stored. Nothing was checked. Call again with the same idempotencyKey. In Ponder, tell the person, who can ask for it again in a new Message.

Authorizations

Authorization
string
header
required

A personal access token, which starts with pat_. A Parable token can call each operation that the roles of its owner allow. An MCP token can call only the read operations that are open to agents. A SQL token does not work on this API.

Headers

X-Tenant
string

Workspace slug. Overrides subdomain-based workspace resolution when provided.

Example:

"acme"

X-Request-ID
string<uuid>

Optional request correlation ID echoed back in the response.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Path Parameters

rootRefId
string
required

rootRefId parameter UUID v4 with automatic base62 encoding for client-facing APIs

Body

application/json

A text file that an agent wrote. It goes through the same name rule, allowlist, size setting and worker check as a person's upload.

fileName
string
required

The file name, such as logo.svg. A name the Parable already has gets a number.

Minimum string length: 1
idempotencyKey
string
required

A new key for each file. The same key with the same name and text stores one file: the call answers that file's current state.

Pattern: ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
text
string
required

The file's whole text.

Minimum string length: 1

Response

Successful response

data
object
required

One file of a Parable as a model reads it. The answer holds the file's bytes when they fit, and never an address for them: a signed download URL stays in web-api. Apart from its image, an answer is fewer than 40,000 characters.

meta
object
required