Service API

All calls go to https://actions.pool.day over TLS with the app key as a bearer token. None carries an image, a file name or a photo identifier. By default PoolKit makes only the first one.

Call	When	What it carries
`POST /sdk/v1/installs`	When the client opens	A random install ID and your bundle ID
`POST /sdk/v1/models`	Before the engine downloads its models	A random install ID and your bundle ID
`POST /sdk/v1/extract`	Cloud assist, naming things	Text read from a capture
`POST /sdk/v1/answer`	Cloud assist, answering a question	The question, and things and short excerpts PoolKit already found
`POST /sdk/v1/profile`	Cloud assist, filling a profile	Your schema, and things and short excerpts PoolKit already found
`POST /sdk/v1/classify`	Cloud assist, judging captures against a rule	Your rule, and text, labels and thing names from the captures PoolKit is unsure about
`POST /sdk/v1/attest/challenge`	App Attest, before the first cloud assist call	A random install ID and your bundle ID
`POST /sdk/v1/attest`	App Attest, once per key	Apple’s attestation of a key made on the device
`POST /sdk/v1/runs`	After an indexing run, only with `sendsRunReports`	Timings and counts of the run: see Run reports

Register an install

POST /sdk/v1/installs
Authorization: Bearer pk_live_…

{ "installId": "0c1d2dbc-…", "bundleId": "com.example.app", "platform": "ios", "sdkVersion": "0.1.0" }

{
  "status": "active",
  "plan": "build",
  "cloudAssist": { "enabled": true },
  "attestation": { "mode": "off" },
  "key": { "expiresAt": null }
}

key.expiresAt is set while a rotated key is in its 30-day grace. When cloud assist is off for the install, cloudAssist says why. { "enabled": false, "reason": "disabled" } means the app turned it off in the dashboard. { "enabled": false, "reason": "quota_exceeded", "retryAfter": 86400 } means the month’s installs or cloud assist units are spent; the SDK registers again after retryAfter seconds and picks up a raised allowance or a new month. Everything on the device keeps working either way. Sent when the client opens. The install ID is random, made by the SDK, stored in your app’s container, and reset when the app is reinstalled. It is how connected users are counted: once per install per calendar month.

List the engine’s models

POST /sdk/v1/models
Authorization: Bearer pk_live_…

{ "installId": "0c1d2dbc-…", "bundleId": "com.example.app" }

{
  "assets": [
    { "assetId": "siglip2-vision", "version": 3, "totalByteCount": 96468992, "files": [
      { "relativePath": "vision.mlmodelc/weights/weight.bin", "url": "https://…", "sha256": "9f2c…", "byteCount": 96201728 }
    ] }
  ]
}

PoolKit downloads each file once, checks it against the SHA-256 given here before loading it, and keeps it in your app’s container. The models run on the device. Nothing about a photo is part of this call.

Cloud assist: name things

POST /sdk/v1/extract
Authorization: Bearer pk_live_…

{
  "installId": "0c1d2dbc-…",
  "bundleId": "com.example.app",
  "items": [
    { "ref": "a1", "source": "screenshots", "text": "Nike Air Max 90\n€149.99", "labels": ["shoe"] }
  ]
}

{
  "results": [
    { "ref": "a1", "things": [
      { "type": "product", "label": "Nike Air Max 90", "attributes": { "price": "€149.99" }, "confidence": 0.9 }
    ] }
  ]
}

Cloud assist: answer a question

POST /sdk/v1/answer
Authorization: Bearer pk_live_…

{
  "installId": "0c1d2dbc-…",
  "bundleId": "com.example.app",
  "question": "Which sneakers did I save?",
  "context": [
    { "ref": "t1", "kind": "thing", "type": "product", "label": "Nike Air Max 90",
      "attributes": { "price": "€149.99" }, "count": 3, "firstSeen": "2026-03-02", "lastSeen": "2026-10-20" },
    { "ref": "c1", "kind": "capture", "text": "Nike Air Max 90 €149.99 Add to bag" }
  ]
}

{ "answer": { "text": "You saved the Nike Air Max 90 three times since March.", "citations": ["t1"], "declined": false } }

The context is what PoolKit found on the device under the grant: up to 40 things and excerpts of up to 400 characters. A ref is a random reference that means nothing outside the request.
Every citation is a ref from the request. Pool drops any other, so an answer cannot point at something the device did not send.
declined is true, with no text, when answering would mean inferring something sensitive or identifying a person.
Pool does not store or log the question, the context or the answer.
A question is 1 to 1,000 characters.

With Accept: text/event-stream, the same call answers as the model writes, for askUpdates. A refusal before the first word is the usual JSON error. Otherwise the body is Server-Sent Events:

event: delta
data: {"text":"You saved the Nike "}

event: delta
data: {"text":"Air Max 90 three times since March."}

event: answer
data: {"answer":{"text":"You saved the Nike Air Max 90 three times since March.","citations":["t1"],"declined":false}}

delta events carry the next words. The final answer is checked like the JSON answer and can be declined after deltas, so drop the text you showed.
When the model fails partway, the last event is error with {"error":{"code","message"},"retryAfter":30} and the units are given back.
The 10 units are charged once the answer event is sent. If the app closes the stream before the first delta, they are given back; once words have arrived, closing it keeps the charge.

Cloud assist: fill a profile

POST /sdk/v1/profile
Authorization: Bearer pk_live_…

{
  "installId": "0c1d2dbc-…",
  "bundleId": "com.example.app",
  "schema": {
    "type": "object",
    "properties": {
      "brands": { "type": "array", "items": { "type": "string" }, "description": "Brands in saved products" },
      "shoeSize": { "type": "number" }
    }
  },
  "context": [ { "ref": "t1", "kind": "thing", "type": "product", "label": "Nike Air Max 90", "count": 3 } ]
}

{
  "profile": {
    "value": { "brands": ["Nike"], "shoeSize": null },
    "evidence": { "/brands": ["t1"] },
    "refused": { "/shoeSize": "no_evidence" }
  }
}

Up to 80 context entries. The schema is a small part of JSON Schema: objects, arrays, strings, numbers, integers, booleans and enums, up to 5 levels, 100 fields and 32 KB. A schema outside that gets a 400 with code invalid_schema and a sentence that says why.
A field is filled only when its value fits the schema and rests on at least one ref from the request. Every other field is null and listed in refused with no_evidence, sensitive or invalid.
Fields about health, religion, sexuality, ethnicity, politics, children, finances or credentials are never filled, whatever the evidence.
Pool does not store or log the schema, the context or the profile.

Cloud assist: judge captures against a rule

POST /sdk/v1/classify
Authorization: Bearer pk_live_…

{
  "installId": "0c1d2dbc-…",
  "bundleId": "com.example.app",
  "rule": "sneakers I might buy",
  "items": [
    { "ref": "c1", "source": "screenshots", "text": "Nike Air Max 90\n€149.99", "labels": ["shoe"], "things": ["Nike Air Max 90"] },
    { "ref": "c2", "source": "photos", "labels": ["sneaker", "footwear"] }
  ]
}

{
  "results": [
    { "ref": "c1", "belongs": 0.93, "incidental": 0.02, "insufficient": 0.05, "member": true }
  ],
  "retryAfterSeconds": 5
}

rule is up to 500 characters of plain words. items holds up to 24 captures; each needs text, a label or a thing name.
belongs is the probability that the capture is what the rule describes. incidental is the probability that it is system or app chrome instead of something the person saved. insufficient is the probability that the text is too thin to judge. member is true when belongs is at least 0.7 and incidental is under 0.45.
A capture missing from results was not reached this time. retryAfterSeconds is present only then and says when to send it again.
Four captures count as one unit, rounded up per request. Captures that were not reached are not charged.
A rule about health, religion, sexuality, ethnicity, politics, children, finances or credentials is refused with 400 and the code rule_not_allowed, before anything is read.
Pool does not store or log the rule or the text. It logs the three numbers per ref, which mean nothing outside the request.

App Attest

Used only when App Attest is on for your app, as the install response’s attestation.mode says.

POST /sdk/v1/attest/challenge
Authorization: Bearer pk_live_…

{ "installId": "0c1d2dbc-…", "bundleId": "com.example.app" }

{ "challenge": "q9X3…", "expiresInSeconds": 300 }

POST /sdk/v1/attest
Authorization: Bearer pk_live_…

{ "installId": "0c1d2dbc-…", "bundleId": "com.example.app", "keyId": "mF2a…", "attestation": "o2NmbXRv…", "challenge": "q9X3…" }

{ "status": "attested" }

A challenge works once, for the install it was made for, for five minutes. Pool keeps only its hash.
The attestation is checked against Apple’s App Attestation root, the challenge, the key ID and <team ID>.<bundle ID>. A live key accepts only production keys. Anything else is a 400 with code attestation_invalid.
Then every cloud assist request carries X-Pool-Attest-Key: <key ID> and X-Pool-Assertion: <base64 assertion>, signed over SHA-256 of the exact body bytes. Each assertion’s counter is accepted once.
Under Enforce, a request without a valid assertion gets 401 with attestation_required, or attestation_key_unknown when the key is not on file. PoolKit attests again once and retries.

Run reports

POST /sdk/v1/runs
Authorization: Bearer pk_live_…

{
  "installId": "0c1d2dbc-…",
  "bundleId": "com.example.app",
  "report": {
    "runId": "4f1c9a2e-…", "kind": "first", "outcome": "completed",
    "startedAt": "2026-11-12T10:00:00Z", "durationMs": 92000,
    "counts": { "total": 1200, "indexed": 1150, "skipped": 40, "failed": 10 },
    "timings": { "readingLibrary": 2000, "indexing": 88000 },
    "peakMemoryMB": 180, "sdkVersion": "0.2.0", "osVersion": "26.1", "deviceModel": "iPhone17,1"
  }
}

Answers 202 { "status": "recorded" }. Any field beyond these is a 400. Kept 90 days.

Status codes

Status	Meaning
200	Success.
400, 413	The request body is malformed or too large.
401	The key is unknown or revoked, or App Attest is enforced and the request is not attested (`attestation_required`, `attestation_key_unknown`).
403	The key is not allowed for this bundle ID (`bundle_not_allowed`), the app is turned off (`app_disabled`) or waits for approval (`app_pending`).
429	Rate limit or allowance reached. `Retry-After` says when to come back.
503	Pool is briefly unavailable. `Retry-After` says when to come back.

Error bodies look like { "error": { "code": "quota_exceeded", "message": "…" } } and never repeat what was sent.

Get started

Guides

Reference

Register an install

List the engine’s models

Cloud assist: name things

Cloud assist: answer a question

Cloud assist: fill a profile

Cloud assist: judge captures against a rule

App Attest

Run reports

Status codes

​Register an install

​List the engine’s models

​Cloud assist: name things

​Cloud assist: answer a question

​Cloud assist: fill a profile

​Cloud assist: judge captures against a rule

​App Attest

​Run reports

​Status codes

Register an install

List the engine’s models

Cloud assist: name things

Cloud assist: answer a question

Cloud assist: fill a profile

Cloud assist: judge captures against a rule

App Attest

Run reports

Status codes