{"components":{"schemas":{"Error":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"type":"object"},"Run":{"properties":{"agent_present":{"type":"boolean"},"awaiting_since":{"type":["string","null"]},"checkpoint":{"description":"The stage result the run waits at (run_key, seq, stage, title, checkpoint_key, opened_at); null when it is not paused. Read GET /runs/{run_key}/checkpoint.","type":["object","null"]},"current_step":{"type":["integer","null"]},"error_message":{"type":["string","null"]},"feedback_count":{"description":"Feedback and proposal entries stored for this run.","type":"integer"},"finished_at":{"type":["string","null"]},"finishing_pending":{"additionalProperties":{"type":"integer"},"description":"Rows each finishing stage still owes (titles, claims, dedup, explanations, translations, headings, reports, contracts, fidelity, provenance, glossaries), as the worker last counted them.","type":"object"},"goal":{"type":"string"},"has_result":{"type":"boolean"},"heartbeat_at":{"type":["string","null"]},"held_tasks":{"description":"Tasks of this run set aside while it waits at a checkpoint.","type":"integer"},"in_flight":{"type":"integer"},"keep_serving":{"description":"True while tasks may still arrive: keep pulling. Always false for a run the server executes (run_mode server).","type":"boolean"},"next_action":{"description":"One sentence: what the run needs from your agent now.","type":"string"},"pauses":{"description":"The run stops after every stage result until the user continues.","type":"boolean"},"posters":{"description":"Whether poster sheets are produced for this run (server-side images).","type":"boolean"},"progress_report":{"description":"A short progress report written for the USER (phase, step, what is still owed by stage, calls answered, time since the start, whether the run waits for your agent, what comes next). Tell it to the user in their language whenever a pull returns it in reports_for_user, and before you end any turn.","type":"string"},"queue_depth":{"type":"integer"},"relay_concurrency":{"type":["integer","null"]},"relay_phase":{"description":"engine: the engine runs; finishing: the engine is done but titles, dedup, explanations, translations and headings still send tasks; done: nothing more will come; stopped: the run ended without finishing.","enum":["engine","finishing","done","stopped",null],"type":["string","null"]},"relay_tasks_failed":{"type":"integer"},"relay_tasks_total":{"type":"integer"},"resumable":{"type":"boolean"},"resume_count":{"type":"integer"},"resumed_from_run_key":{"type":["string","null"]},"run_key":{"type":"string"},"run_mode":{"description":"server: the Eternal Search server answers every model call of this run; follow the status, read the outcome. agent_relay: your agent answers the calls as tasks.","enum":["server","agent_relay"],"type":"string"},"server_run":{"description":"True when run_mode is server.","type":"boolean"},"skill_revision":{"description":"Revision of the skill files on the server; compare with GET /skill/version when it changes, and update your copy.","type":["string","null"]},"started_at":{"type":["string","null"]},"status":{"enum":["executing","awaiting_user_llm","completed","completed_at_step","failed_at_execute","failed_at_persist","interrupted_at_step","stopped_awaiting_user_llm"],"type":"string"},"step_detail":{"type":["string","null"]},"step_name":{"type":["string","null"]},"test_mode":{"type":"boolean"},"total_elapsed_seconds":{"type":["number","null"]},"translate_ru":{"description":"Whether Russian versions are produced for this run.","type":"boolean"}},"type":"object"},"Task":{"properties":{"attempt":{"type":"integer"},"max_tokens":{"type":["integer","null"]},"messages":{"items":{"properties":{"content":{"type":"string"},"role":{"type":"string"}},"type":"object"},"type":"array"},"response_format":{"description":"{\"type\":\"json_object\"} when the answer must be one JSON object.","type":["object","null"]},"run_key":{"type":"string"},"task_id":{"type":"string"},"temperature":{"type":["number","null"]},"tier":{"description":"The model tier the engine asked for. Map it to your own model; the model name never crosses the wire.","enum":["high","mid","low"],"type":"string"},"timeout_s":{"description":"Answer within this many seconds of pulling, or the engine re-issues the task.","type":"integer"}},"type":"object"}},"securitySchemes":{"linkToken":{"description":"The token returned once by POST /links.","scheme":"bearer","type":"http"}}},"info":{"contact":{"url":"https://eternalsearch.net/omega-point/agents"},"description":"The Omega Point engine on the Eternal Search server orchestrates a full research run (steps, prompts, literature search, deduplication, validation, state). At present every run started here executes on the server (the response and the status say run_mode server): your agent starts it, follows GET /runs/{key} and reads the outcome; it pulls no tasks. When the server hands model calls to agents instead (run_mode agent_relay), every call the engine needs comes to your agent as a task: pull it, answer it with your model, complete it; each task names a tier (high, mid, low). The link token is the only credential. The run goes the same way as one started on the public site: the engine to the hypotheses of step 7, then titles, deduplication, explanations, question headings, translations and the Russian report; relay_phase is engine, then finishing, then done; GET /runs/{key}/result answers 202 until then. Russian versions (translate_ru) and poster sheets (posters) are the user's choice on POST /runs: ask before starting. Poster images are drawn by the server. After the run, ask the user for feedback and post it with POST /runs/{key}/feedback, together with the corrections or improvements your agent proposes; the operator reads them. A 502 or a reset connection is a restart of a few seconds: repeat the same call after 15 s; links, runs and pulled tasks survive it.","title":"Omega Point Agent Relay","version":"1.0.0"},"openapi":"3.1.0","paths":{"/links":{"post":{"operationId":"registerLink","requestBody":{"content":{"application/json":{"schema":{"properties":{"agent_kind":{"enum":["claude_code","codex","cursor","cowork","script","mcp","other"],"type":"string"},"concurrency":{"description":"How many tasks your agent answers at once: the engine fans out that wide inside a run. A Codex login serves 4 well; a Claude Code login 1 (its credential file races on refresh); an API key 4 or more. Change it later with PATCH /links/current.","maximum":256,"minimum":1,"type":"integer"},"provider_label":{"description":"Display only, e.g. \"Codex subscription\". No secrets.","type":"string"},"tier_models":{"properties":{"high":{"type":"string"},"low":{"type":"string"},"mid":{"type":"string"}},"type":"object"}},"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"base_url":{"type":"string"},"concurrency":{"type":"integer"},"link_id":{"type":"string"},"pull_url":{"type":"string"},"skill_url":{"type":"string"},"token":{"type":"string"}},"type":"object"}}},"description":"Link created"},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"type":"object"}}},"description":"Bad input"}},"security":[{}],"summary":"Register an agent link (anonymous). Returns the token once."}},"/links/current":{"get":{"operationId":"currentLink","responses":{"200":{"description":"Link"}},"summary":"This link and its live queue state"},"patch":{"operationId":"updateLink","requestBody":{"content":{"application/json":{"schema":{"properties":{"concurrency":{"maximum":256,"minimum":1,"type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"Updated link"},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"type":"object"}}},"description":"Bad input"}},"summary":"Change how many tasks you answer at once. Applies to the next pull and the run's next fan-out."}},"/parallelism":{"get":{"operationId":"parallelism","responses":{"200":{"description":"The plan"}},"security":[{}],"summary":"Which units of a run are independent, and the priority lanes the queue drains in order"}},"/runs":{"get":{"operationId":"listRuns","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"runs":{"items":{"$ref":"#/components/schemas/Run"},"type":"array"}},"type":"object"}}},"description":"Runs"}},"summary":"Runs of this link"},"post":{"operationId":"startRun","requestBody":{"content":{"application/json":{"schema":{"properties":{"global_lens":{"type":"string"},"goal":{"description":"The user's question in the user's own words and language, as they wrote it. Not a brief: no counts, ranking criteria, per-item templates, methods or deliverables (pages, translations, posters); the engine decides those itself.","maxLength":4000,"type":"string"},"pauses":{"default":true,"description":"Stop after every stage result (engine steps, every 10 hypotheses, the engine output, titles and duplicates, every 10 rewritten and every 10 translated hypotheses) until the user continues, so no agent turn has to outlast a stage. false = unattended.","type":"boolean"},"posters":{"default":false,"description":"Produce poster sheets for the run's hypotheses (drawn by the server). Ask the user before starting; false skips them.","type":"boolean"},"translate_ru":{"default":true,"description":"Produce Russian versions (translations, Russian headings, report, poster sheet). Ask the user before starting; false skips all of them.","type":"boolean"}},"required":["goal"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"handoff_text":{"description":"Give this to the user verbatim: they paste it into a new session if this one ends, and that session finishes the run. Also in the status and in the resume response (with the new key).","type":"string"},"queued_position":{"description":"Server mode: the place in the queue when the pool is full; null when the run started at once.","type":["integer","null"]},"run_key":{"type":"string"},"run_mode":{"enum":["server","agent_relay"],"type":"string"},"status_url":{"type":"string"}},"type":"object"}}},"description":"Started"}},"summary":"Start a run on this link (run_mode server: executes on the server, up to three runs per person at a time, queued when the pool is full)"}},"/runs/{run_key}":{"get":{"operationId":"runStatus","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"run":{"$ref":"#/components/schemas/Run"}},"type":"object"}}},"description":"Run"},"404":{"description":"Not this link's run"}},"summary":"Status, step, counters, awaiting_since, relay_phase (serve until done)"}},"/runs/{run_key}/checkpoint":{"get":{"operationId":"runCheckpoint","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"checkpoint, run, instructions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"type":"object"}}},"description":"Not paused"}},"summary":"The stage result the run waits at: summary_markdown (write it to the user in their language) and body_markdown (the complete result, save it as a file). 404 no_checkpoint when the run is not paused."}},"/runs/{run_key}/checkpoints":{"get":{"operationId":"runCheckpoints","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"checkpoints"}},"summary":"Every stage stop of the run, in order, without bodies"}},"/runs/{run_key}/checkpoints/{seq}":{"get":{"operationId":"runCheckpointBySeq","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}},{"in":"path","name":"seq","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"checkpoint"}},"summary":"One stage stop with its texts"}},"/runs/{run_key}/continue":{"post":{"operationId":"continueRun","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"continued, released_tasks, checkpoint, run"},"409":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"type":"object"}}},"description":"nothing_to_continue"}},"summary":"The user said to continue: release the checkpoint, put the held tasks back. The body names the next checkpoint when it is already due. Call it only on the user's word."}},"/runs/{run_key}/documents":{"get":{"operationId":"runDocuments","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Manifest: folder, languages, files, index texts, counts"},"404":{"description":"No run with that key"},"409":{"description":"run_not_done, nothing_published, or no_public_site on a server without public pages"}},"security":[{},{"linkToken":[]}],"summary":"The document folder of any run whose pages are final (publication finished or stopped), open with or without a token: one markdown file per published open question and hypothesis per language, with the text and structure of its page on the site (every hypothesis file ends with its assessment: eight 0-10 ratings with reasons, findings, limits and the complete abstracts read), an index per language (index.en.md, index.ru.md) and the published poster sheets as PNG files. Lists every file name (its relative path in the folder), kind, language, public id, page URL, and for posters the image_url to download. 409 run_not_done while the pages are still being finished, 409 nothing_published when the run published nothing."}},"/runs/{run_key}/documents/file":{"get":{"operationId":"runDocumentFile","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}},{"in":"query","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file"},"400":{"description":"Malformed name"},"404":{"description":"Not a file of this run"},"409":{"description":"Run not done"},"502":{"description":"The page could not be rendered now; retry"}},"security":[{},{"linkToken":[]}],"summary":"One file of the folder by its name: a markdown document in full (content, chars, words; poster images inside point at the PNG files of the folder), or for a poster its image_url. One file per call."}},"/runs/{run_key}/feedback":{"get":{"operationId":"listFeedback","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"feedback":{"items":{"properties":{"author":{"description":"user: what the person said; agent: what your agent wrote.","enum":["user","agent"],"type":"string"},"body":{"maxLength":20000,"type":"string"},"kind":{"description":"feedback: a remark on the result; proposal: a concrete correction or improvement.","enum":["feedback","proposal"],"type":"string"},"target_id":{"description":"The hypothesis public_id, the stage name, etc. Omit for the run.","type":"string"},"target_kind":{"default":"run","enum":["run","hypothesis","explanation","question","stage"],"type":"string"}},"required":["author","kind","body"],"type":"object"},"type":"array"}},"type":"object"}}},"description":"Entries"}},"summary":"Feedback and proposals stored for a run"},"post":{"operationId":"addFeedback","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"properties":{"author":{"description":"user: what the person said; agent: what your agent wrote.","enum":["user","agent"],"type":"string"},"body":{"maxLength":20000,"type":"string"},"kind":{"description":"feedback: a remark on the result; proposal: a concrete correction or improvement.","enum":["feedback","proposal"],"type":"string"},"target_id":{"description":"The hypothesis public_id, the stage name, etc. Omit for the run.","type":"string"},"target_kind":{"default":"run","enum":["run","hypothesis","explanation","question","stage"],"type":"string"}},"required":["author","kind","body"],"type":"object"},{"properties":{"entries":{"items":{"properties":{"author":{"description":"user: what the person said; agent: what your agent wrote.","enum":["user","agent"],"type":"string"},"body":{"maxLength":20000,"type":"string"},"kind":{"description":"feedback: a remark on the result; proposal: a concrete correction or improvement.","enum":["feedback","proposal"],"type":"string"},"target_id":{"description":"The hypothesis public_id, the stage name, etc. Omit for the run.","type":"string"},"target_kind":{"default":"run","enum":["run","hypothesis","explanation","question","stage"],"type":"string"}},"required":["author","kind","body"],"type":"object"},"maxItems":20,"type":"array"}},"required":["entries"],"type":"object"}]}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"stored":{"items":{"properties":{"author":{"description":"user: what the person said; agent: what your agent wrote.","enum":["user","agent"],"type":"string"},"body":{"maxLength":20000,"type":"string"},"kind":{"description":"feedback: a remark on the result; proposal: a concrete correction or improvement.","enum":["feedback","proposal"],"type":"string"},"target_id":{"description":"The hypothesis public_id, the stage name, etc. Omit for the run.","type":"string"},"target_kind":{"default":"run","enum":["run","hypothesis","explanation","question","stage"],"type":"string"}},"required":["author","kind","body"],"type":"object"},"type":"array"}},"type":"object"}}},"description":"Stored"},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"message":{"type":"string"}},"type":"object"}}},"description":"Bad entry"}},"summary":"Store the user's feedback and your proposed corrections or improvements on a run (any status)"}},"/runs/{run_key}/outcome":{"get":{"operationId":"runOutcome","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}},{"in":"query","name":"texts","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Outcome"},"404":{"description":"No run with that key"}},"security":[{},{"linkToken":[]}],"summary":"What the run published, for the user: per open question its English and Russian page URLs, the published hypotheses under it with their URLs, the size of every text (characters and words, counted), run totals; ?texts=true adds the full texts so you can paste them into the chat in any format the user asks. Each hypothesis carries assessment: status, the eight 0-10 scores and api_url, the open API item with the full assessment. Open for ANY run key, with or without a token, including runs started on the site or by another link. Works in any phase: publication is publishing, finished or stopped; complete=false while the pages are still being finished."}},"/runs/{run_key}/result":{"get":{"operationId":"runResult","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}},{"in":"query","name":"engine_only","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Result or saved steps"},"202":{"description":"Still running"}},"summary":"Full result JSON once relay_phase is done (same shape as the workbench result); 202 while the engine runs or the finishing stages still serve (?engine_only=true reads the engine result early)"}},"/runs/{run_key}/resume":{"post":{"operationId":"resumeRun","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"The run continues under the SAME run_key; the body carries resume_count and the handoff_text for the user"},"409":{"description":"Not resumable (live, finished, or restarted by a concurrent resume)"}},"summary":"Continue a lost or parked run under its own key from its saved steps (repeatable) A run whose engine finished but whose finishing phase was stopped is revived (relay_phase back to finishing, same key)."}},"/runs/{run_key}/stop":{"post":{"operationId":"stopRun","parameters":[{"in":"path","name":"run_key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stopped"}},"summary":"Stop the run; completed steps stay saved and resumable. On a run whose engine is done it ends the finishing phase (relay_phase stopped; POST /runs/{run_key}/resume revives it later)"}},"/skill":{"get":{"operationId":"skillPackage","responses":{"200":{"description":"Files as JSON strings, with their revision and sha256"}},"security":[{}],"summary":"The skill package: SKILL.md, the Node connector, MCP config"}},"/skill/version":{"get":{"operationId":"skillVersion","responses":{"200":{"description":"revision, files_sha256, download_urls, how_to_check"}},"security":[{}],"summary":"The current revision and the sha256 of every skill file. Compare your copy before a run, a resume and a new session; any difference means it is outdated."}},"/tasks/pull":{"post":{"operationId":"pullTasks","requestBody":{"content":{"application/json":{"schema":{"properties":{"max_tasks":{"description":"At most your link concurrency.","type":"integer"},"wait_s":{"maximum":25,"type":"number"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"checkpoint_instructions":{"type":["string","null"]},"checkpoints":{"description":"Runs of this link waiting at a stage stop; their tasks are held. Finish the answers in hand, pull no more, show the user the checkpoint and end your turn (checkpoint_instructions).","type":"array"},"in_flight":{"type":"integer"},"queue_depth":{"type":"integer"},"reports_for_user":{"description":"Progress reports due now (at a stage change and at least every 10 minutes): tell each progress_report to the user at once, in their language, then carry on serving.","items":{"properties":{"progress_report":{"type":"string"},"reason":{"type":"string"},"relay_phase":{"type":["string","null"]},"run_key":{"type":"string"}},"type":"object"},"type":"array"},"skill_revision":{"description":"Revision of the skill files on the server; when it differs from the one you saw at the start, check your copy against GET /skill/version.","type":["string","null"]},"tasks":{"items":{"$ref":"#/components/schemas/Task"},"type":"array"}},"type":"object"}}},"description":"Zero or more tasks"}},"summary":"Long-poll up to 25 s for model calls to answer. The pull is your heartbeat."}},"/tasks/{task_id}/complete":{"post":{"operationId":"completeTask","parameters":[{"in":"path","name":"task_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"properties":{"content":{"type":"string"},"model":{"type":"string"},"usage":{"properties":{"completion_tokens":{"type":"integer"},"prompt_tokens":{"type":"integer"}},"type":"object"}},"required":["content"],"type":"object"},{"properties":{"error":{"properties":{"kind":{"type":"string"},"message":{"type":"string"}},"required":["message"],"type":"object"}},"required":["error"],"type":"object"}]}}},"required":true},"responses":{"200":{"description":"Accepted"},"410":{"description":"The engine stopped waiting; a fresh attempt was issued"}},"summary":"Post the model answer, or an error"}},"/tasks/{task_id}/release":{"post":{"operationId":"releaseTask","parameters":[{"in":"path","name":"task_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Back in the queue"}},"summary":"Give a pulled task back untouched (you are shutting down)"}}},"security":[{"linkToken":[]}],"servers":[{"url":"https://eternalsearch.net/omega-point/api/agent/v1"}]}