HTTP API reference

Use the HTTP API when integrating EnvLoop into a service that cannot use the Python SDK. For an interactive terminal, the CLI handles authentication, output and resource commands for you.

All business jobs use /v1/job: submit with type=agent|sandbox|train|inference (default agent), and list training with ?type=train. Details and results identify job_id, with training fields under training; stop with POST /v1/job/{job_id}/stop. Retired jobs/train/sessions APIs are removed; upgrade the platform and clients together. Native protocol create_session/session_id stays inside its protocol adapter.

Addresses and authentication

Purpose	Address	Authentication
Website and product information	`https://envloop.ai`	Public pages
Browser Console	`https://console.envloop.ai`	Browser sign-in
CLI, SDK and resource API	`https://api.envloop.ai`	Bearer API key
OpenAI-compatible inference	`https://api.envloop.ai/v1/job/YOUR_JOB_ID/Inference`	Authorized project key and a ready endpoint
Compatible training SDK protocol	`https://api.envloop.ai/v1/job/tinker`	Project key through `TINKER_CREDENTIAL_CMD`

Create a project key in the Console as described in Authentication. Set ENVLOOP_API_KEY through your shell's secret input or your service's secret manager. Never put a key into a page URL or frontend bundle.

curl --fail-with-body --silent --show-error \
  https://api.envloop.ai/v1/me \
  -H "Authorization: Bearer $ENVLOOP_API_KEY"

A successful response establishes who the key represents and its permitted scope. A browser session and an API key are distinct credentials. An endpoint existing in this reference does not mean every key may call it: user-only account actions require the signed-in Console, and project operations also check resource ownership and capabilities.

Workspace and project context

The SDK sends X-Workspace-ID and X-Project-ID when configured. You can use the same headers in an HTTP integration:

curl --fail-with-body --silent --show-error \
  'https://api.envloop.ai/v1/job?limit=10' \
  -H "Authorization: Bearer $ENVLOOP_API_KEY" \
  -H "X-Workspace-ID: $ENVLOOP_WORKSPACE_ID" \
  -H "X-Project-ID: $ENVLOOP_PROJECT_ID"

Use the actual IDs from your selected context, not display names. Headers select context; they do not grant access outside the key's scope. Avoid accidentally reusing another project's environment variables. If context is omitted, use the resolved context returned by the platform rather than assuming which project was selected.

Resource map

The following paths are relative to the resource API origin. Braced identifiers are placeholders; URL-encode ordinary ID parameters. Dataset and Profile logical names instead require unpadded base64url of their UTF-8 bytes. A name such as team/data cannot be inserted directly or merely percent-encoded; prefer SDK helpers for these names. For request bodies and validated examples, follow the linked guide or the matching SDK method. Do not guess fields from the Console's display text.

Resource	Main paths	User workflow
Identity and current context	`/v1/me`; browser-only context via `/v1/session-context`	Connect and verify identity
Jobs	`/v1/job`, `/v1/job/{job_id}`, `/v1/job/{job_id}/result`	Submit, inspect and stop work
Job evaluation snapshot	`/v1/job/{job_id}/leaderboard`	Compare aggregate results
Trials	`/v1/trials`, `/v1/trials/{trial_id}`, `/detail`, `/logs`, `/result` under a Trial	Inspect one attempt
Trial artifacts	`/v1/trials/{trial_id}/artifacts`, artifact content and download routes	Read output files
Datasets	`/v1/datasets`, `/v1/datasets/{encoded_name}/versions`, version task lists	Select a dataset revision
Profiles	`/v1/profiles`, profile detail, versions and default selection	Reuse execution parameters
Checkpoints	`/v1/job/checkpoints`, `/v1/job/checkpoints/{checkpoint_id}`, `…/ttl`, `…/visibility`, `/v1/job/checkpoints/copy`, `/v1/job/checkpoints/usage`, download routes	Save, inspect and recover
Serving profiles	`/v1/serving/profiles`	Choose a supported serving profile
Adapters	`/v1/adapters`, `/v1/adapters/{adapter_id}`	Register trained weights
Endpoints	`/v1/endpoints`, `/v1/endpoints/{endpoint_id}`, endpoint events and actions	Deploy, pause and resume inference
Cleanup operations	`/v1/projects/{project_id}/cleanup-operations`, `/v1/projects/{project_id}/operations/{operation_id}`, operation retry	Track asynchronous cleanup
Temporary resource scopes	`/v1/projects/{project_id}/temporary-resource-scopes`, scope detail and retain routes	Keep selected training outputs
Billing	`/v1/billing/account`, `/ledger`, `/prices`, `/usage`; workspace-scoped billing routes	Interpret usage and charges
Workspaces and projects	`/v1/workspaces`, workspace project lists and project detail	Choose and manage context
Membership and invitations	Workspace members/invitations; project members/member-candidates routes	Manage permitted access
Project credentials	Project `/api-keys` and `/service-accounts` routes	Manage keys and machine identities
Project limits	Project `/limits` route	Understand resource limits

Training uses managed Jobs: discover recipes with client.training_jobs.models() and submit with client.training_jobs.submit(request). Public interactive training is removed; see migration.

Managed discovery: GET /v1/job/training-models returns configured project-scoped recipes, frozen revisions, modalities, features/limits (labels, parent checkpoint, hyperparameter ranges, loss mask, sequence length) and the request schema. A type=train Job returns the labels, effective hyperparameters and parent_checkpoint it was admitted with, and its checkpoint.path once it succeeds; see Qwen3.8-27B options. readiness=configured does not guarantee admission or GPU capacity. Removed interactive routes return 410 INTERACTIVE_TRAINING_REMOVED; Job/checkpoint/history and normal inference retain their permissions.

Read a result without creating new work

curl --fail-with-body --silent --show-error \
  "https://api.envloop.ai/v1/job/$JOB_ID/result" \
  -H "Authorization: Bearer $ENVLOOP_API_KEY" \
  -H "X-Workspace-ID: $ENVLOOP_WORKSPACE_ID" \
  -H "X-Project-ID: $ENVLOOP_PROJECT_ID"

Record the original resource ID immediately after submission. Poll that resource with a bounded interval and deadline. A successful submission is acceptance of work; it does not establish that execution, scoring, checkpoint upload or deployment has finished. Interpret each resource's state using its guide.

For a new Job, use the supported request_id through the SDK or submission contract to recover from an uncertain network response. Reuse it only for the same intended request; a changed experiment needs a new ID. Read before retrying a write. Do not repeatedly create endpoints or training jobs while waiting for readiness.

Pagination and downloads

List endpoints may return a continuation cursor. Preserve the original filters and pass the returned cursor to the next request; stop when the response has no continuation. A single page is not the full collection. Field names and limits are resource-specific; use the matching CLI help or SDK method rather than assuming every list has the same envelope.

For downloads, use the supported SDK/CLI helpers where possible. Signed download links expire and contain their own authorization. If your integration follows a storage redirect, do not forward the platform Bearer key or context headers to the storage host. Validate the expected file size/hash when provided, and refresh the download request if its link expires.

Handle errors

Response	Check first	Next action
`400` / `422`	Request fields, identifier format, supported options	Fix the request; repeated identical retries will not help
`401`	Missing, expired or revoked key; wrong API origin	Verify the key with `/v1/me` and update the saved configuration
`403`	Key capability, project role or a user-only operation	Use an appropriately authorized account; context headers cannot elevate permissions
`404`	Resource ID, project context, deletion or resource visibility	Confirm the resource in the same project before creating a replacement
`409`	Concurrent change, state conflict or operation preconditions	Refresh the resource and apply the change to its current state
`429`	Rate limit and any retry guidance	Back off within a bounded deadline
`5xx` / timeout	Transient service failure or work still in progress	Read the existing resource before retrying a write; keep the request/resource ID

When requesting support, include UTC time, method/path, HTTP status, returned error code, and relevant resource/request IDs. Remove Authorization headers, signed URLs and private task contents. See Troubleshooting.

Next steps

CLI reference · Python SDK reference · Inference endpoints · Client configuration

Addresses and authentication​

Workspace and project context​

Resource map​

Read a result without creating new work​

Pagination and downloads​

Handle errors​

Next steps​