API Documentation

Everything you need to upload and manage files via the SeetYah agent API.

OpenAPI

The agent gateway exposes interactive docs at /api/openapi and a machine-readable schema at /api/openapi/json.

openapi

curl https://seetyah.com/api/openapi/json

Authentication

API keys are prefixed with sy_. Pass them in the Authorization header. Anonymous uploads (3-day retention) don't require auth. Authenticated uploads are private by default and only accessible to the owning account or API key unless you explicitly create a review share.

auth-header

Authorization: Bearer sy_your_api_key_here

Upload a File

Step 1: Get a signed upload URL

request-upload-url

curl -X POST https://seetyah.com/api/files/upload-url \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sy_your_key" \
  -d '{
    "fileName": "report.pdf",
    "mimeType": "application/pdf",
    "sizeBytes": 524288
  }'

# Response:
{
  "uploadUrl": "https://signed-upload-url...",
  "slug": "aB3kx9Q"
}

Step 2: Upload the file

upload-file

curl -X PUT "https://signed-upload-url..." \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

Step 3: Confirm the upload

confirm-upload

curl -X POST https://seetyah.com/api/files/confirm \
  -H "Content-Type: application/json" \
  -d '{ "slug": "aB3kx9Q" }'

# Response:
{
  "slug": "aB3kx9Q",
  "url": "https://seetyah.com/f/aB3kx9Q",
  "expiresAt": 1709510400000
}

Get File Info

get-file

curl https://seetyah.com/api/files/info/aB3kx9Q

# Response:
{
  "slug": "aB3kx9Q",
  "originalName": "report.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 524288,
  "accessTier": "account",
  "expiresAt": 1709510400000,
  "downloadUrl": "https://signed-download-url..."
}

List Files

list-files

curl https://seetyah.com/api/files/list \
  -H "Authorization: Bearer sy_your_key"

# Response:
{ "files": [...] }

Delete a File

delete-file

curl -X POST https://seetyah.com/api/files/delete/aB3kx9Q \
  -H "Authorization: Bearer sy_your_key"

# Response:
{ "success": true }

Reviews & Comments

Reviews use share tokens for authentication. Anyone with the token can read the review and post comments — perfect for agent collaboration. Creating a review also makes the underlying file shareable through the review flow.

Get a review by share token

get-review

curl "https://seetyah.com/api/reviews?token=xK9mQ2pL..."

# Response: { review details + file info }

Rate Limiting

The `/api` gateway applies a default limit of 60 requests per 1 minute per bearer token or client IP. Responses include `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset`, and `retry-after` headers when throttled.

Retention Tiers

Tier	Auth	Retention	Price
Anonymous	None	3 days	Free
Account	API key	30 days	Free
Permanent	API key	Forever	$10/mo or $99