Percio API v1 Base URL: https://rl.percio.xyz/api/v1 Authorization: Bearer YOUR_API_KEY Create a key in the customer web app's "For your engineers and AI agents (API)" section. Keys are shown once. Never include a key in prompts, logs or source control. Full guide: https://rl.percio.xyz/api/v1/guide Interactive docs: https://rl.percio.xyz/api/v1/docs Start: GET /me and GET /areas. POST /projects {"sample":true} creates a project with area/workflows already chosen. Or POST /projects {"name":"Team","expert_hours":1}, PUT /projects/{project}/area {"area":"ID_FROM_AREAS"}, PUT /projects/{project}/workflows {"workflows":[{"title":"Job","description":"Work to do","tool":"spreadsheet","deliverable":"result.xlsx","kind":"KIND_FROM_AREA"}]}. Own-data recipe (instead of fixed catalog workflows): 1. Create a named project and choose its area as above. 2. POST /projects/{project}/gradings:from-records with {file_name,content_base64,title,request,deliverable,send_to,holdout_fraction:0.2,mask_private:false}. Without columns this previews first-five rows, suggested columns and privacy, saving nothing. Confirm input_columns (facts) and output_columns (correct answers) in a second call. Keep answer values out of request. 3. Or POST /projects/{project}/gradings:from-examples with {files:[{file_name,content_base64}],title,request,deliverable,send_to,mask_private:false}. Without roles it previews summary/figures; repeat with roles:{label:graded|given|skip} to draft. At most 20 files. Neither route uses a model or approves automatically. 4. GET /projects/{project}/gradings and GET /projects/{project}/gradings/{grading_id} to inspect plain checks, good/mistake/blank scores, readiness problems, practice/holdout counts and public worked-example request. No held-out answer keys or file bytes are returned. PATCH the latter with {checks:[{index:0,weight:0.8,keep:true}],tolerance_pct:2} to adjust checks and retry samples. Check indices start at zero; tolerance is >0 and <=20; weights are nonnegative relative shares. 5. After actual expert review, POST /projects/{project}/gradings/{grading_id}:approve {approved_by:"Name"}. Readiness problems return 422; approval adds/replaces its custom workflow without removing others. Approved gradings cannot be patched (409); create a new one instead. 6. POST /projects/{project}/tasks:generate, poll the job, then continue the normal expert task review and quality steps. Uploads are base64 JSON, body including encoding <=25 MB and decoded files <=25 MB; invalid encoding is 422, oversized 413. Project isolation applies to all these routes. Python: gradings_from_records, gradings_from_examples, gradings, grading, patch_grading, approve_grading. MCP: gradings_from_records, gradings_from_examples, list_gradings, get_grading, patch_grading, approve_grading. Step order: 1 area: PUT /projects/{project}/area 2 workflows: PUT /projects/{project}/workflows (tools: spreadsheet, document, email, slides; optional include_standard true|false = also add the area's standard tasks, default off when every workflow is graded from the customer's own data) 3 tasks: POST /projects/{project}/tasks:generate, then GET /projects/{project}/tasks 4 expert review: read tasks and grading; obtain expert approval before POST /projects/{project}/tasks/{task_id}/decision {"decision":"approve","reviewer":"Name"}. Reject with decision reject and a note. DELETE the decision endpoint to reopen. Many tasks of one workflow: GET /projects/{project}/review/groups; after the expert approves spot_check (3) of a workflow by hand with none rejected, POST /projects/{project}/review/groups/{workflow}:approve-rest {"reviewer":"Name"} approves the rest (DELETE the same path undoes it). Decide all, then POST /projects/{project}/review:finish {"reviewer":"Name"}. 5 quality: POST /projects/{project}/quality-checks then GET same endpoint for verdict/checks. Optional model comparisons: GET /models/check-options, POST /projects/{project}/model-checks {"models":["ID1","openrouter:ANY_OPENROUTER_ID"],"custom":[{"name":"Ours","endpoint":"https://YOUR-PROVIDER/v1","model":"MODEL","api_key":"KEY"}]} (2-4 total; custom = customer's own OpenAI-compatible HTTPS model, billed by their provider, key never stored), GET /projects/{project}/model-checks/latest. 6 package: POST /projects/{project}/package 7 training: GET /training/options; POST /projects/{project}/training:plan then POST /projects/{project}/training with {"provider":"own-gpu-trl","base_model":"Qwen/Qwen3-8B","budget_usd":25}. GET /projects/{project}/training refreshes status. Own GPUs or your-account providers prepare a handover, not completed training; we-run providers start a managed job. Never imply a handover has measured training results. 8 report: POST /projects/{project}/report then GET /projects/{project}/files; download the report artifact's url. Report only requires completed expert review and can summarize partial progress. Project JSON includes next_action: read it after every action; it names what to do and the endpoint. Steps expose status and message. Do not continue past failed steps. GET /projects lists only your workspace; GET /projects/{project} resumes work. Generate, quality, package and report return 202 {job_id,status:"running",status_url}. Poll status_url about every two seconds until done, failed or interrupted. Returned URLs begin /v1: resolve them against https://rl.percio.xyz/api (do not duplicate /v1). GET /jobs/{job_id} includes message, project and result_url. Only done means success. Interrupted means the API restarted; explicitly retry the original action. Busy means poll the active job before changing this project. Errors: {"error":{"code":"step_locked","message":"Plain explanation","next_step":"Finish review"}}. next_step is optional. 401 invalid/missing/revoked credential; 404 unknown or other customer's resource; 409 step_locked or busy; 422 invalid_input with the action's explanation; 413 body too large; 429 rate_limited with Retry-After seconds; 503 capability unavailable. Correct the input or finish next_step; do not blindly retry. Limits: 120 requests per minute per customer (all keys together), body at most 25 MB, max 5 active keys, model checks $2 each / one at a time per project / $20 per customer per month, training budget_usd at most 5000. All artifact downloads must use returned file URLs, not server paths. URL-encode path segments. Health, guides and interactive docs/schema are public; resources require Bearer auth. ## Use Percio from AI agents (MCP) From a local checkout, install the official SDK and optional Python client: ```sh python -m pip install mcp python -m pip install ./clients/python ``` The server supports official SDK 1.x FastMCP and SDK 2.x (where FastMCP was renamed MCPServer). Run it with `python -m src.mcp_server.server` from the checkout root for stdio, or `python -m src.mcp_server.server --http 8000` for streamable HTTP at `/mcp`. HTTP binds all interfaces: put it behind an authenticated TLS proxy before exposing it to remote agents; callers share the customer API key and can write to the server's local filesystem via download_file. Use a local stdio server unless you need remote access. ### Claude Desktop Merge this into `claude_desktop_config.json`; replace the absolute checkout and Python paths and the key placeholder with your actual values: ```json { "mcpServers": { "percio": { "command": "/absolute/path/to/venv/bin/python", "args": ["-m", "src.mcp_server.server"], "env": { "PYTHONPATH": "/absolute/path/to/percio-checkout", "PERCIO_API_KEY": "YOUR_API_KEY" } } } } ``` ### Claude Code From the checkout root, with PERCIO_API_KEY already exported in your shell: ```sh claude mcp add --transport stdio --env "PERCIO_API_KEY=$PERCIO_API_KEY" --env "PYTHONPATH=$PWD" percio -- python -m src.mcp_server.server ``` This stores the key in your local MCP configuration; keep that configuration private and outside source control. ### Cursor Use the same `mcpServers` JSON above in your private user-level `~/.cursor/mcp.json` (or a private project `.cursor/mcp.json` that is never committed). The command, args and env are identical to Claude Desktop; absolute paths allow any working directory. Restart the client after configuring it. Read resource `percio://guide` or invoke prompt `build_environment` to follow all eight steps. `get_project` returns steps and next_action. Generation, quality, packaging and reports wait for completion and return the final job plus project. Tools return JSON error envelopes with message and next_step instead of hiding API refusals. An expert must actually read the tasks and grading before approving any task. Do not automatically approve generated tasks. Training handovers do not mean a model has trained. Model checks and managed training can incur costs; review the plan and budget before starting them. ### Python client quickstart Set PERCIO_API_KEY in your environment, then run this sample-to-PDF walkthrough: ```python from percio_client import PercioClient c = PercioClient() # Reads PERCIO_API_KEY slug = c.create_sample()['slug'] c.wait(c.generate(slug)) tasks = c.tasks(slug)['tasks'] for task in tasks: print(task) # Expert must read briefs, grading and expected values assert input('Expert has actually reviewed all tasks? Type yes: ') == 'yes' for task in tasks: c.decide(slug, task['task_id'], 'approve', reviewer='Expert') c.finish_review(slug, reviewer='Expert') c.wait(c.run_quality_checks(slug)) c.wait(c.report(slug)) # Report can summarize partial progress pdf = next(f for f in c.files(slug)['files'] if f['name'].endswith('.pdf')) c.download(pdf['url'], 'report.pdf') ``` The dependency-free module is `percio_client` (distribution `percio-client`). `PercioError` carries code, message, next_step and HTTP status. Slow methods return a job; `wait` polls every two seconds by default and raises on failed/interrupted jobs or timeout. A 429 respects Retry-After with at most five retries. Artifacts are saved with `download(url_path, dest_path)`, which returns local path and size. Scoring: one answer per label (label first, number next to it). Alternatives ("3.44 or 4.47", ranges, lists, "3.44 (4.47)") and decisions naming two options earn 0. See API.md "How answers are scored".