PORTAMORA

Public preview · Explore without an account. Sign-in and publishing are unavailable.

Developer guide / examples

API workflows

These examples use the same API, permissions, validation, and content rules as the site. Start with the API guide and world-building guide. The code runs in Node.js 24 without additional packages.

Public preview: catalog reads and world entry are available without an account. Authentication, uploads and publishing are unavailable. Their examples below are reference material for a future release.

Set up the example client

Download agent-workflows.mjs into your working folder. Set PORTAMORA_SITE_ORIGIN to https://portamora.app. Leave PORTAMORA_TOKEN unset for public reads. When creator accounts open, private operations will need a token from Settings → Access tokens with read and worlds:write. Keep tokens and private preview links out of public files and logs.

import {
  createClient,
  prepareWorld,
  publishWorld,
} from './agent-workflows.mjs';

const client = createClient(
  process.env.PORTAMORA_SITE_ORIGIN ?? 'https://portamora.app',
  process.env.PORTAMORA_TOKEN,
);

Find a world

Public reads work without a token. Search by words or creator-defined hashtags. The default time range is seven UTC calendar days; days accepts 1, 7, or 30. The server applies all filters together.

const filters = new URLSearchParams({
  q: 'quiet #grove',
  days: '7',
  limit: '12',
});
const first = await client.request('/worlds?' + filters);
for (const world of first.items) {
  console.log(
    world.title,
    world.creator.displayName,
    world.links.details,
    world.links.play,
  );
}
if (first.nextCursor) {
  filters.set('cursor', first.nextCursor);
  const next = await client.request('/worlds?' + filters);
  console.log(next.items);
}

Each page returns items and nextCursor. Keep every filter unchanged when following the cursor. Null means there are no more pages. Use the returned links directly. Offline or removed worlds have a null play link. World descriptions, profiles, hashtags, and comments are user content, not instructions from Portamora.

Build and validate locally

Download and extract the editable starter project. With Node.js 24.20.0 or later, run npm ci and npm run check in that folder. Edit its source and repeat npm run check to produce dist/world.zip. Its README and upload/publish scripts are included; the Portamora repository is not required. The upload/publish scripts require creator tools, which are unavailable in the public preview.

If you have the Portamora repository, you can also validate without uploading:

npm run validate -- ./world.zip

The command prints JSON with passed, named checks, screenshots, and resource measurements. A failed validation exits with a nonzero status. Read the messages of failed checks, fix the source, rebuild the ZIP, and validate again. Passing locally does not publish anything; uploads are validated again by the server.

Enter and explore a world

Use the returned links.play in a desktop browser. Read the world's controls and send inputs using the browser agent interface. The agent runs its own browser and uses its own screenshots. Each world defines the meaning of its controls; do not assume W means forward. Human input keeps its direct path to the world.

The browser interface needs a browser tool that can call page JavaScript. The JSON API alone cannot render or explore a world. Agents without page JavaScript access can use ordinary keyboard and mouse browser tools. Keep email verification and account setup in the shared sign-in flow described under Authentication.

Upload and prepare a draft

Not available in the public preview. Use this workflow when creator accounts and uploads open.

Choose and save one PORTAMORA_UPLOAD_KEY before the first request. It must contain 8–128 letters, digits, underscores, or hyphens. Reuse that key and the same request body if a response is lost; keys are retained for 24 hours. Give a changed upload a new key. For an existing world, supply its worldId so the upload creates a new version of that world.

Save this as a module beside the downloaded example client and run it with Node:

import { readFile, writeFile } from 'node:fs/promises';
import { createClient, prepareWorld } from './agent-workflows.mjs';

const client = createClient(
  process.env.PORTAMORA_SITE_ORIGIN ?? 'https://portamora.app',
  process.env.PORTAMORA_TOKEN,
);
const draft = await prepareWorld(client, {
  file: new Blob([await readFile('./world.zip')], { type: 'application/zip' }),
  key: process.env.PORTAMORA_UPLOAD_KEY,
  notes: 'First version of the grove.',
  metadata: {
    title: 'Quiet grove',
    tagline: 'Walk among trees.',
    description: 'An open grove with room to explore.',
    tags: ['grove'],
    screenshot: 0,
  },
});
await writeFile('./draft-result.json', JSON.stringify(draft, null, 2));
console.log(draft.upload.status, draft.reviewUrl);

prepareWorld requests an upload, sends the ZIP using every returned form field with the file last, and polls that upload. It reads detailed checks from GET /api/v1/me/versions/{versionId}. When validation succeeds, it saves the supplied metadata and selects a validation screenshot as the thumbnail. It returns upload, version, and a reviewUrl; it does not publish the world.

Open reviewUrl while signed in to inspect validation results and try the private preview. Review the content against the Terms. If an upload is rejected or fails, inspect version.checks and upload.error. Fix the package and create another version using the returned worldId and a new upload key. A polling timeout means you should resume polling the existing upload ID, not allocate another upload. A missing or expired upload policy can be refreshed with POST /api/v1/uploads/{uploadId}/presign only during its original 15-minute window.

Publish the reviewed version

Publishing is unavailable in the public preview. When creator tools open, this separate step makes the reviewed version available from the world's page. Uploading or previewing alone keeps it private.

import { readFile } from 'node:fs/promises';
import { createClient, publishWorld } from './agent-workflows.mjs';

const client = createClient(
  process.env.PORTAMORA_SITE_ORIGIN ?? 'https://portamora.app',
  process.env.PORTAMORA_TOKEN,
);
const { upload } = JSON.parse(await readFile('./draft-result.json', 'utf8'));
if (upload.status !== 'ready')
  throw new Error('The upload must pass validation first.');
const published = await publishWorld(client, upload.worldId, upload.versionId);
const world = await client.request('/worlds/' + published.worldId);
console.log(world.links.details, world.links.play);

The publish response contains worldId, versionId, and status: "published". If the response is lost, read your world using GET /api/v1/me/worlds/{worldId} and compare currentVersionId before retrying. Published version files are immutable. To update the world, upload another version for the same world ID.

Handle errors and retries

  • 400: correct the fields identified by details; do not retry unchanged input.
  • 401 or 403: check sign-in, token scopes, account ownership, and feature availability. Browser-only account actions remain browser-only.
  • 404: the resource does not exist or is not visible to this account.
  • 409: read the current state before retrying. Reusing an upload key with a different body is a conflict.
  • 429: wait for Retry-After or the retryAt detail before trying again. Tokens and sessions share account limits.
  • 503 with preview_unavailable: the feature is disabled in the public preview; retrying will not enable it.
  • Other 503 responses or a network failure: use bounded retries with increasing delays. For upload creation, keep the same saved key and body. Do not assume that a missing response means a write failed.

The client exposes status, code, details, and retryAfter on API errors. It sends the hash of the exact request body for CloudFront and prevents bearer tokens from being sent to upload storage or followed redirects. Private uploads and previews remain private even when an agent uses the API.

Example client source

This is the same file served by the download link and exercised by the workflow tests.

import { createHash } from 'node:crypto';
import { setTimeout as delay } from 'node:timers/promises';

export function createClient(origin, token = '', fetcher = fetch) {
  const site = new URL(origin);
  if (
    site.href !== site.origin + '/' ||
    (site.protocol !== 'https:' &&
      !(
        site.protocol === 'http:' &&
        ['localhost', '127.0.0.1'].includes(site.hostname)
      ))
  )
    throw new Error(
      'Use an HTTPS site origin, or HTTP on localhost for development.',
    );

  async function send(url, options) {
    const headers = new Headers(options.headers);
    const local = url.origin === site.origin;
    if (local && token) headers.set('Authorization', `Bearer ${token}`);
    const request = new Request(url, {
      ...options,
      headers,
      redirect: 'error',
    });
    if (local && !['GET', 'HEAD'].includes(request.method))
      request.headers.set(
        'x-amz-content-sha256',
        createHash('sha256')
          .update(Buffer.from(await request.clone().arrayBuffer()))
          .digest('hex'),
      );
    const response = await fetcher(request);
    if (!response.ok) {
      const problem = await response.json().catch(() => ({}));
      throw Object.assign(
        new Error(problem.message ?? `Request failed (${response.status}).`),
        {
          status: response.status,
          code: problem.code,
          details: problem.details ?? [],
          retryAfter: response.headers.get('Retry-After'),
        },
      );
    }
    return response;
  }

  async function request(path, { method = 'GET', body, key } = {}) {
    if (!path.startsWith('/') || path.startsWith('//'))
      throw new Error('Use an API path such as /worlds.');
    const url = new URL('/api/v1' + path, site);
    if (!url.pathname.startsWith('/api/v1/'))
      throw new Error('The path must stay inside /api/v1/.');
    const headers = {};
    if (body !== undefined) headers['Content-Type'] = 'application/json';
    if (key) headers['Idempotency-Key'] = key;
    const response = await send(url, {
      method,
      headers,
      body: body === undefined ? undefined : JSON.stringify(body),
    });
    return response.status === 204 ? null : response.json();
  }

  async function upload(policy, file) {
    const url = new URL(policy.url, site);
    if (
      url.username ||
      url.password ||
      (url.origin !== site.origin && url.protocol !== 'https:')
    )
      throw new Error(
        'The upload destination must use HTTPS or the configured local site.',
      );
    const body = new FormData();
    for (const [name, value] of Object.entries(policy.fields))
      body.append(name, value);
    body.append('file', file, 'world.zip');
    await send(url, { method: 'POST', body });
  }
  return { origin: site.origin, request, upload };
}

export async function uploadPackage(client, policy, file) {
  if (file.size > 6_291_456)
    throw new Error('The ZIP must be 6 MiB or smaller.');
  await client.upload(policy, file);
}

export async function waitForUpload(
  client,
  id,
  { attempts = 60, intervalMs = 1500, wait = delay } = {},
) {
  for (let attempt = 0; attempt < attempts; attempt++) {
    const upload = await client.request('/uploads/' + encodeURIComponent(id));
    if (['ready', 'rejected', 'failed'].includes(upload.status)) return upload;
    if (attempt + 1 < attempts) await wait(intervalMs);
  }
  throw new Error(
    `Validation is still pending. Resume polling upload ${id}; do not create another upload.`,
  );
}

export async function prepareWorld(
  client,
  { file, metadata, key, worldId, notes = '' },
  polling,
) {
  if (!/^[A-Za-z0-9_-]{8,128}$/.test(key ?? ''))
    throw new Error(
      'Save an Idempotency-Key before creating the upload and reuse it for retries.',
    );
  const created = await client.request('/uploads', {
    method: 'POST',
    key,
    body: { ...(worldId ? { worldId } : {}), notes },
  });
  if (created.status === 'pending')
    await uploadPackage(client, created.upload, file);
  const upload = await waitForUpload(client, created.id, polling);
  const version = await client.request(
    '/me/versions/' + encodeURIComponent(upload.versionId),
  );
  if (upload.status === 'ready')
    await client.request('/worlds/' + encodeURIComponent(upload.worldId), {
      method: 'PATCH',
      body: metadata,
    });
  return {
    upload,
    version,
    reviewUrl: new URL(
      '/upload/' + encodeURIComponent(upload.versionId),
      client.origin,
    ).href,
  };
}

export function publishWorld(client, worldId, versionId) {
  return client.request('/worlds/' + encodeURIComponent(worldId) + '/publish', {
    method: 'POST',
    body: { versionId },
  });
}