Client¶

/v1/client is what a client reads before it can do anything else: the working agreement that tells an agent how to use Companions, and the versions of Portal the API accepts. Both reads are free and need no credential, so Portal can fetch them before anyone has logged in.

Endpoints¶

Method	Path	Purpose
`GET`	`/v1/client/agreement`	The working agreement, as one text with its version. Cached for an hour. Free.
`GET`	`/v1/client/versions`	The minimum and deprecated Portal versions. Cached for five minutes. Free.

The working agreement¶

text is the same string the remote MCP server sends in its initialize instructions. version rises whenever the wording changes, so a client only has to compare the integer.

Portal versions¶

{"portal": {"minimum": "0.9.5", "deprecated_below": "0.10.1"}}

Field	Meaning
`minimum`	The lowest Portal that may start new work. Below it, new billed runs are refused.
`deprecated_below`	Portal below this version still works, and tells its user to update.
`sunset`	Present only when a floor is about to rise: a sentence such as `The floor rises to 0.10.1 on 2026-12-01.`

Channel data (which version is on stable, latest or experimental) comes from the Portal download host, not from this API.

How the minimum is enforced¶

Portal 0.10.1 and later send User-Agent: portal/<version>. A request that names a version below minimum on POST /v1/completion or POST /v1/discover is refused before anything is enqueued or charged:

HTTP/1.1 426 Upgrade Required
Upgrade: portal/0.9.5

{"details": {
  "error_type": "portal_update_required",
  "message": "Portal 0.9.4 is below the minimum safe version 0.9.5 and refuses new work until it is updated. Stop and tell the user to run `portal update` in their terminal. If you hold a pending job_id, collect it with get_answer first. Do not run the command yourself and do not retry this call.",
  "fix": "Run `portal update` in your terminal.",
  "minimum": "0.9.5",
  "current": "0.9.4"
}}

Every other caller is unaffected: a missing User-Agent, any agent that is not portal/<version>, and unstamped portal/dev builds all pass. Reads and /v1/jobs/* are never refused, so a run that was already paid for can always be collected.