Programmatic tools

Public discovery runs on haneoka.org. Job endpoints run on your local service; see the local computation guide for startup and complete examples.

Discover

Discover the API

GETHEAD /api/v1

Machine-readable entry points, request contracts and tool modules.

Authentication: None. Public, anonymous read.
Caching: public, max-age=300

Example request

cURL
JavaScript

curl -sS "https://haneoka.org/api/v1"

const response = await fetch("https://haneoka.org/api/v1");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

Example response

HTTP/2 200 OK

{}

Trimmed for length; the real response contains more entries.

Complete OpenAPI

GETHEAD /api/v1/openapi.json

Machine-readable entry points, request contracts and tool modules.

Authentication: None. Public, anonymous read.
Caching: public, max-age=300

Example request

cURL
JavaScript

curl -sS "https://haneoka.org/api/v1/openapi.json"

const response = await fetch("https://haneoka.org/api/v1/openapi.json");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

Example response

HTTP/2 200 OK

{}

Trimmed for length; the real response contains more entries.

Device computation modules

GETHEAD /api/v1/tools

Machine-readable entry points, request contracts and tool modules.

Authentication: None. Public, anonymous read.
Caching: public, max-age=300

Example request

cURL
JavaScript

curl -sS "https://haneoka.org/api/v1/tools"

const response = await fetch("https://haneoka.org/api/v1/tools");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

Example response

HTTP/2 200 OK

{}

Trimmed for length; the real response contains more entries.

Local computation

Local service capabilities

GET /v1

Lists operations, queue concurrency and result lifetime.

Authentication: Local service Bearer token. Read the private headers file printed at startup.
Caching: no-store

Example request

cURL
JavaScript

curl -sS "http://127.0.0.1:8765/v1" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1", {
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

Example response

HTTP/2 200 OK

{
  "operations": [
    "search",
    "evaluate",
    "growth",
    "timeline",
    "chart-image"
  ],
  "concurrency": 1,
  "resultTtlSeconds": 600
}

Errors

Status	Code	Meaning
`400`	`invalid_request`	An ID in the path or query is malformed.
`401`	`unauthorized`	Supply the local Bearer token.
`403`	`origin_not_allowed`	Call from a local client or script.
`404`	`not_found`	Unknown region or record.
`404`	`job_not_found`	Job expired or was removed.
`409`	`image_not_ready`	Wait for image completion.
`413`	`body_too_large`	Request exceeds 2 MiB.
`429`	`rate_limit_exceeded`	Too many requests for this key; honour `Retry-After` when present.
`429`	`queue_full`	Wait for an active job or delete expired results.

Submit a local calculation

POST /v1/jobs

Returns 202 and a Location to poll. Bodies: 2 MiB; queue: eight; execution: one job, five minutes. Inventories stay on this host.

Authentication: Local service Bearer token. Read the private headers file printed at startup.
Caching: no-store

Request body application/json

Name	Type	Description
`operation`required	string	search, evaluate, growth, timeline, chart-image or resource-image.
`request`optional	object	Required for calculations; use the corresponding type in tools/schema.json.

Example request

cURL
JavaScript

curl -sS -X POST "http://127.0.0.1:8765/v1/jobs" \
  -H "Authorization: Bearer ${localToken}" \
  -H "Content-Type: application/json" \
  --data '{"operation":"chart-image","server":"intl","songId":"100001","difficulty":"expert","locale":"en","height":720}'

const response = await fetch("http://127.0.0.1:8765/v1/jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${localToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "operation": "chart-image",
    "server": "intl",
    "songId": "100001",
    "difficulty": "expert",
    "locale": "en",
    "height": 720
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

Example response

HTTP/2 202 Accepted
Location: /v1/jobs/00000000-0000-4000-8000-000000000001

{
  "id": "00000000-0000-4000-8000-000000000001",
  "operation": "chart-image",
  "state": "queued"
}

Errors

Status	Code	Meaning
`400`	`invalid_request`	An ID in the path or query is malformed.
`401`	`unauthorized`	Supply the local Bearer token.
`403`	`origin_not_allowed`	Call from a local client or script.
`404`	`not_found`	Unknown region or record.
`404`	`job_not_found`	Job expired or was removed.
`409`	`image_not_ready`	Wait for image completion.
`413`	`body_too_large`	Request exceeds 2 MiB.
`429`	`rate_limit_exceeded`	Too many requests for this key; honour `Retry-After` when present.
`429`	`queue_full`	Wait for an active job or delete expired results.

Read job progress and result

GET /v1/jobs/{id}

States: queued, running, completed, failed. Results expire ten minutes after completion. Read result, identity and optional image URL.

Authentication: Local service Bearer token. Read the private headers file printed at startup.
Caching: no-store

Parameters

Name	In	Type	Description
`id`required	path	uuid	Job ID returned by submission.

Example request

cURL
JavaScript

curl -sS "http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001", {
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

Example response

HTTP/2 200 OK

{
  "id": "00000000-0000-4000-8000-000000000001",
  "operation": "search",
  "state": "completed",
  "createdAt": 1793030400000,
  "expiresAt": 1793031000000,
  "result": {
    "overall": [],
    "results": [],
    "stopReason": "complete"
  }
}

Errors

Status	Code	Meaning
`400`	`invalid_request`	An ID in the path or query is malformed.
`401`	`unauthorized`	Supply the local Bearer token.
`403`	`origin_not_allowed`	Call from a local client or script.
`404`	`not_found`	Unknown region or record.
`404`	`job_not_found`	Job expired or was removed.
`409`	`image_not_ready`	Wait for image completion.
`413`	`body_too_large`	Request exceeds 2 MiB.
`429`	`rate_limit_exceeded`	Too many requests for this key; honour `Retry-After` when present.
`429`	`queue_full`	Wait for an active job or delete expired results.

Cancel and delete a job

DELETE /v1/jobs/{id}

Closes the calculation context and removes the saved result. Later reads return 404.

Authentication: Local service Bearer token. Read the private headers file printed at startup.
Caching: no-store

Parameters

Name	In	Type	Description
`id`required	path	uuid	Job ID returned by submission.

Example request

cURL
JavaScript

curl -sS -X DELETE "http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);

Example response

HTTP/2 204 No Content

No response body.

Errors

Status	Code	Meaning
`400`	`invalid_request`	An ID in the path or query is malformed.
`401`	`unauthorized`	Supply the local Bearer token.
`403`	`origin_not_allowed`	Call from a local client or script.
`404`	`not_found`	Unknown region or record.
`404`	`job_not_found`	Job expired or was removed.
`409`	`image_not_ready`	Wait for image completion.
`413`	`body_too_large`	Request exceeds 2 MiB.
`429`	`rate_limit_exceeded`	Too many requests for this key; honour `Retry-After` when present.
`429`	`queue_full`	Wait for an active job or delete expired results.

Download a completed image

GET /v1/jobs/{id}/image.png

Requires a completed chart-image job and the same local Bearer token. Returns PNG; 409 while not ready.

Authentication: Local service Bearer token. Read the private headers file printed at startup.
Caching: no-store

Parameters

Name	In	Type	Description
`id`required	path	uuid	Job ID returned by submission.

Example request

cURL
JavaScript

curl -sS -o output.bin "http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001/image.png" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001/image.png", {
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const blob = await response.blob();

Example response

HTTP/2 200 OK

Binary body (not shown).

Errors

Status	Code	Meaning
`400`	`invalid_request`	An ID in the path or query is malformed.
`401`	`unauthorized`	Supply the local Bearer token.
`403`	`origin_not_allowed`	Call from a local client or script.
`404`	`not_found`	Unknown region or record.
`404`	`job_not_found`	Job expired or was removed.
`409`	`image_not_ready`	Wait for image completion.
`413`	`body_too_large`	Request exceeds 2 MiB.
`429`	`rate_limit_exceeded`	Too many requests for this key; honour `Retry-After` when present.
`429`	`queue_full`	Wait for an active job or delete expired results.

Render a resource image locally

POST /v1/resource-image

Uses the same image recipes as the resource APIs. JSON: 8 MiB, output: 16 MiB, deadline: 50 seconds, one job at a time. See the image export guide for kind, data and viewer state.

Authentication: Local service Bearer token. Read the private headers file printed at startup.
Caching: no-store

Request body application/json

Name	Type	Description
`kind`required	string	team, gacha, gacha-history, stamp, chart, live2d or spine.
`data`required	object	Website export model; see /reference/images/.

Example request

cURL
JavaScript

curl -sS -o output.bin -X POST "http://127.0.0.1:8765/v1/resource-image" \
  -H "Authorization: Bearer ${localToken}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @resource-image.json

const response = await fetch("http://127.0.0.1:8765/v1/resource-image", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${localToken}`,
    "Content-Type": "application/octet-stream",
  },
  body: file,
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const blob = await response.blob();

Example response

HTTP/2 200 OK

Binary body (not shown).

Errors

Status	Code	Meaning
`400`	`invalid_request`	An ID in the path or query is malformed.
`401`	`unauthorized`	Supply the local Bearer token.
`403`	`origin_not_allowed`	Call from a local client or script.
`404`	`not_found`	Unknown region or record.
`404`	`job_not_found`	Job expired or was removed.
`409`	`image_not_ready`	Wait for image completion.
`413`	`body_too_large`	Request exceeds 2 MiB.
`429`	`rate_limit_exceeded`	Too many requests for this key; honour `Retry-After` when present.
`429`	`queue_full`	Wait for an active job or delete expired results.

Download report image ZIP

GET /v1/jobs/{id}/images.zip

Use the exact image URL returned by a completed resource-image archive job.

Authentication: Local service Bearer token. Read the private headers file printed at startup.
Caching: no-store

Parameters

Name	In	Type	Description
`id`required	path	uuid	Job ID returned by submission.

Example request

cURL
JavaScript

curl -sS -o output.bin "http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001/images.zip" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001/images.zip", {
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const blob = await response.blob();

Example response

HTTP/2 200 OK

Binary body (not shown).

Errors

Status	Code	Meaning
`400`	`invalid_request`	An ID in the path or query is malformed.
`401`	`unauthorized`	Supply the local Bearer token.
`403`	`origin_not_allowed`	Call from a local client or script.
`404`	`not_found`	Unknown region or record.
`404`	`job_not_found`	Job expired or was removed.
`409`	`image_not_ready`	Wait for image completion.
`413`	`body_too_large`	Request exceeds 2 MiB.
`429`	`rate_limit_exceeded`	Too many requests for this key; honour `Retry-After` when present.
`429`	`queue_full`	Wait for an active job or delete expired results.