External Outputs API

Overview

The External Outputs API lets an outside system fetch a project's run results — status, logs, and output files — without a user logging in. It's intended for integrations: a scheduled job, dashboard, or another service that needs to pull the latest result on its own schedule.

Each API key is scoped to exactly one project's notebook; there's no project-id parameter on any endpoint below — the key itself determines which project's outputs you get back.

Authentication

Every request needs an Authorization header with a key prefixed pk_:

Authorization: Bearer pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requests without this header, with a malformed value, or with an unknown key get back 401 Unauthorized.

Get a key

There isn't a self-serve settings page for this yet. Create a key by calling the key-management endpoint directly, authenticated with your normal platform session token (the same one the web app and CLI use):

curl -X POST https://api.harumi.io/api/keys/<NOTEBOOK_ID> \
  -H "Authorization: Bearer <your platform session token>"

This returns the pk_... key exactly once — store it immediately, since it can't be retrieved again (only rotated or revoked). Each user currently has at most one key at a time; creating a second one while you have an active key returns 409 Conflict. To rotate it:

curl -X PATCH https://api.harumi.io/api/keys/<NOTEBOOK_ID> \
  -H "Authorization: Bearer <your platform session token>"

Endpoints

Base URL: https://api.harumi.io/api/external/outputs

curl https://api.harumi.io/api/external/outputs \
  -H "Authorization: Bearer pk_..."

Response shapes

GET /api/external/outputs and .../latest return an output object:

The two .../files endpoints return the same shape plus a files array:

{
  "id": "01J...",
  "status": "finished",
  "started": "2026-08-01T12:00:00Z",
  "ended": "2026-08-01T12:03:14Z",
  "files": [
    {
      "name": "results/output.csv",
      "extension": "csv",
      "size": 4021,
      "url": "https://...s3...&X-Amz-Expires=3600"
    }
  ]
}

Each file's url is a presigned S3 URL valid for 1 hour. If the run didn't produce a downloadable output, files is an empty array.

Errors