> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentsfleet.net/llms.txt > Use this file to discover all available pages before exploring further. # Request the next work assignment > Returns the next work assignment, or how long to wait before polling again. Previously held fleet sandboxes are preferred. Required `accepted_kinds` selects fleet work, private setup work, or both. Budget, approval, and policy checks happen before assignment. ## OpenAPI ````yaml https://raw.githubusercontent.com/agentsfleet/agentsfleet/main/public/openapi.json post /v1/runners/me/leases openapi: 3.1.0 info: title: agentsfleet API description: API for managing workspaces, fleets, triggers, and runs. contact: name: agentsfleet url: https://agentsfleet.net license: name: MIT identifier: MIT version: 1.0.0 servers: - url: https://api.agentsfleet.net description: Production security: [] paths: /v1/runners/me/leases: post: tags: - Runners summary: Request the next work assignment description: >- Returns the next work assignment, or how long to wait before polling again. Previously held fleet sandboxes are preferred. Required `accepted_kinds` selects fleet work, private setup work, or both. Budget, approval, and policy checks happen before assignment. operationId: runner_lease requestBody: content: application/json: schema: $ref: '#/components/schemas/LeaseRequest' required: true responses: '200': description: A lease to run, or a backoff to wait out content: application/json: schema: $ref: '#/components/schemas/LeaseResponse' '400': description: Invalid polling body or kind selection content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '401': description: Authentication is missing, invalid, or not accepted by this endpoint content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '403': description: You do not have permission for this action content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '413': description: The request body exceeds this endpoint's size limit content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '429': description: A request or capacity limit has been reached content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '500': description: An internal server error occurred content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '503': description: A required service is unavailable content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' security: - RunnerBearerAuth: [] components: schemas: LeaseRequest: type: object description: >- Runner's request for work. Lists held fleet sandboxes to prefer their next events; an empty list may be omitted. Accepted work kinds are required. required: - accepted_kinds properties: accepted_kinds: type: array items: $ref: '#/components/schemas/LeaseWorkKind' description: The nonempty set of work protocols implemented by this worker. maxItems: 2 minItems: 1 holds: type: array items: type: string maxLength: 36 minLength: 36 description: >- Every fleet this runner holds a frozen sandbox for. Absent decodes as empty. maxItems: 64 additionalProperties: false LeaseResponse: type: object description: >- `POST /v1/runners/me/leases` reply. Always `200`. `lease` is the work, or null with `retry_after_ms` set when there is none — a backoff hint rather than a `204`. properties: lease: oneOf: - $ref: '#/components/schemas/TaggedLease_Value' description: The work, when there is any. - type: 'null' retry_after_ms: type: - integer - 'null' format: int32 description: How long to wait before asking again, when there is none. minimum: 0 ProblemBody: type: object description: The body every refusal carries, under `application/problem+json`. required: - docs_uri - title - detail - error_code - request_id properties: action_id: type: - string - 'null' description: 'On that 409 only: the action the gate held.' current_state: type: - string - 'null' description: 'On a 409 only: the state that forbade the transition.' detail: type: string description: One sentence on what was refused and why. docs_uri: type: string description: Where the error code is documented. error_code: type: string description: The registry code, stable across releases. etag: type: - string - 'null' description: >- On a 412 only: the resource's current entity tag, to refetch and retry. gate_id: type: - string - 'null' description: 'On an answered approval gate''s 409 only: the gate that was answered.' outcome: type: - string - 'null' description: 'On that 409 only: the answer that stands.' request_id: type: string description: The request this refusal answers, for support. resolved_at: type: - string - 'null' format: date-time description: 'On that 409 only: when the standing answer was given.' resolved_by: type: - string - 'null' description: 'On that 409 only: who gave it.' title: type: string description: A short name for the refusal, safe to show a person. user_message: type: - string - 'null' description: A curated sentence for end users, where the code has one. LeaseWorkKind: type: string description: The two independent work domains sharing a physical host's workers. enum: - fleet - authoring TaggedLease_Value: oneOf: - allOf: - $ref: '#/components/schemas/LeasePayload' description: Installed fleet work, with its runtime policy. - type: object required: - kind properties: kind: type: string enum: - fleet description: Installed fleet work, with its runtime policy. - allOf: - $ref: '#/components/schemas/Lease_Value' description: >- Private setup work with limited access to the server's model endpoint. - type: object required: - kind properties: kind: type: string enum: - authoring description: >- Private setup work with limited access to the server's model endpoint. description: >- Placement alone determines which protocol and authority the worker receives. LeasePayload: type: object description: >- Work assigned to a runner. Return its `fencing_token` with updates; the server rejects older tokens after reassignment. required: - lease_id - fencing_token - lease_expires_at - secret_delivery - event - policy - instructions - history - resume_hold properties: event: $ref: '#/components/schemas/EventEnvelope' description: The event to run. fencing_token: type: integer format: int64 description: Monotonic guard a report must echo. minimum: 0 history: type: array items: $ref: '#/components/schemas/Turn' description: |- The fleet's earlier turns, oldest first, ahead of this event; empty unless the event is a chat message. instructions: type: string description: >- The installed fleet's behaviour prose, so the sandboxed turn runs the installed behaviour rather than a generic one. Soft reasoning input — hard tool and secret policy stays in `policy`. lease_expires_at: type: string format: date-time description: The instant after which the event becomes reclaimable. lease_id: type: string description: Identifier for this lease. limits: oneOf: - $ref: '#/components/schemas/SandboxLimits' description: >- The sandbox to run in; null uses this runner's configured defaults. - type: 'null' policy: $ref: '#/components/schemas/ExecutionPolicy' description: What the run is permitted to do. resume_hold: type: boolean description: >- True when the runner can reuse its latest held sandbox for a new event. Reassigned events and expired or outdated sandboxes require a fresh sandbox. secret_delivery: $ref: '#/components/schemas/SecretDelivery' description: How secrets reached this run. Lease_Value: type: object description: Work for a trusted authoring worker; confers no fleet tool authority. required: - lease_id - attempt_id - draft_id - sequence - fence - expires_at - deadline - model - model_access - messages - limits properties: attempt_id: type: string description: Content-free accounting obligation identity. candidate: type: - object - 'null' description: Current immutable candidate, including its identity and revision. deadline: type: string format: date-time description: Original attempt deadline; renewal cannot extend it. draft_id: type: string description: Private source conversation identity. expires_at: type: string format: date-time description: The lease deadline. fence: type: string description: Decimal attempt fencing token. lease_id: type: string description: Durable lease identity. limits: $ref: '#/components/schemas/Limits' description: Enforced attempt budgets. messages: type: array items: $ref: '#/components/schemas/ContextMessage' description: Bounded private conversation context. model: $ref: '#/components/schemas/SelectedModel' description: Non-secret selected model metadata. model_access: $ref: '#/components/schemas/ModelAccess' description: >- Permission to call the server's model endpoint for this specific attempt. sequence: type: string description: Decimal sequence of the admitted request. EventEnvelope: type: object description: >- An event and its original request body. The runner reads `request_json`; API responses return it unchanged. required: - event_id - fleet_id - workspace_id - actor - event_type - request_json - created_at properties: actor: type: string description: Who or what produced the event. created_at: type: string format: date-time description: When the event was created. event_id: type: string description: |- The canonical event identifier, the same on every surface that shows the event. event_type: $ref: '#/components/schemas/EventType' description: How the event entered the system. fleet_id: type: string description: The fleet this event belongs to. request_json: type: string description: Original request body, returned unchanged. workspace_id: type: string description: The workspace the fleet belongs to. Turn: type: object description: |- One earlier exchange in the fleet's thread: what was asked, and what the fleet answered. required: - message - answer properties: answer: type: string description: >- The fleet's answer, or the fixed text a reply-less or failed run reads as. message: type: string description: The event's message, as `event::message_of` reads it. SandboxLimits: type: object description: >- Required sandbox resources. The runner refuses values outside the published limits. Whether the host has enough capacity is checked separately. required: - cpu_millis - memory_bytes - disk_bytes properties: cpu_millis: type: integer format: int32 description: Processor share, in thousandths of one core. maximum: 32000 minimum: 250 disk_bytes: type: integer format: int64 description: The workspace disk's size, in bytes. maximum: 274877906944 minimum: 1073741824 memory_bytes: type: integer format: int64 description: Memory, in bytes. maximum: 68719476736 minimum: 268435456 ExecutionPolicy: type: object description: Everything a single run is permitted to do. required: - network_policy - tools - mintable - provider - api_key - inference_host - http_origin_policies - context properties: api_key: type: string description: >- Provider credential for this run. Secret — never logged, never echoed. base_url: type: - string - 'null' description: Base URL override for a compatible provider. context: $ref: '#/components/schemas/ContextBudget' description: Context-budget knobs for the run. http_origin_policies: type: array items: $ref: '#/components/schemas/HttpOriginPolicy' description: Per-host request boundaries. inference: oneOf: - $ref: '#/components/schemas/ModelInference' description: >- Saved model inference settings, required for runtime provider connections. - type: 'null' inference_host: type: string description: Inference host to dial. mintable: type: array items: $ref: '#/components/schemas/Mintable' description: Integration credentials this run may request when needed. model_context_tokens: type: integer format: int32 description: >- Saved physical model context, independent of the fleet's operating cap. Zero is unresolved and cannot authorize a provider connection. minimum: 0 network_policy: $ref: '#/components/schemas/NetworkPolicy' description: Where the run may reach on the network. provider: type: string description: Inference provider name. repository_binding: oneOf: - $ref: '#/components/schemas/RepositoryBinding' description: Repositories the run is bound to, when it is bound to any. - type: 'null' secrets_map: description: >- Static secrets substituted at the tool boundary. Free-form by design. tools: type: array items: type: string description: Tools the run may call. SecretDelivery: type: string description: How tenant secrets reach the runner. enum: - inline - scoped - proxy Limits: type: object description: Limits applied to both server model requests and private setup work. required: - input_per_call - output_per_turn - max_calls - wall_seconds - provider_timeout_seconds properties: input_per_call: type: integer format: int64 description: Maximum assembled input for one model request. max_calls: type: integer format: int64 description: Maximum physical dispatch count. output_per_turn: type: integer format: int64 description: Shared output allowance across every physical dispatch. provider_timeout_seconds: type: integer format: int64 description: Maximum duration of one provider request. wall_seconds: type: integer format: int64 description: Maximum attempt duration. ContextMessage: type: object description: Private context, oldest first and including the current user message. required: - role - text properties: role: $ref: '#/components/schemas/ContextRole' description: Untrusted conversational role. text: type: string description: Retained private text. SelectedModel: type: object description: One selected model's non-secret identity and pinned prices. required: - ref - provider - model - pricing properties: model: type: string description: Selected provider model identifier. pricing: $ref: '#/components/schemas/Pricing' description: Integer prices; no floating-point money enters the protocol. provider: type: string description: Approved transport identity. ref: type: string description: Explicit owner registry reference. ModelAccess: type: object description: Only the authenticated holder of this lease may present this capability. required: - token - expires_at - invocation_path properties: expires_at: type: string format: date-time description: Current lease expiry, capped by the attempt deadline. invocation_path: type: string description: >- Relative path of the server's model endpoint. Provider addresses and credentials are not returned. token: type: string description: Random capability; never log or spool it. EventType: type: string description: How an event entered the system. enum: - chat - webhook - cron - continuation ContextBudget: type: object description: >- Context-budget knobs. `model` and `context_cap_tokens` are upstream-populated passthrough — the runner does not interpret `model`. required: - tool_window - memory_checkpoint_every - stage_chunk_threshold - model - context_cap_tokens properties: context_cap_tokens: type: integer format: int32 description: The fleet's operating context cap, or zero when unresolved. minimum: 0 memory_checkpoint_every: type: integer format: int32 description: How often a run checkpoints its memory. minimum: 0 model: type: string description: The active model, carried through without interpretation. stage_chunk_threshold: type: number format: float description: |- Fill fraction at which a stage chunks rather than growing: 0 to 1 of the context window. maximum: 1 minimum: 0 tool_window: type: integer format: int32 description: Tool results retained in the working window. minimum: 0 HttpOriginPolicy: type: object description: The provider-neutral request boundary for one exact host. required: - host - credential_names - requests properties: credential_names: type: array items: type: string description: Credentials admitted at this host. host: type: string description: The host this boundary governs. requests: type: array items: $ref: '#/components/schemas/HttpRequestRule' description: Requests admitted at this host. ModelInference: type: object description: >- Admin-owned model settings; credentials remain separate vault references. required: - api - base_url - max_output_tokens properties: api: $ref: '#/components/schemas/InferenceApi' description: Explicit provider API; never inferred from a model identifier. base_url: type: string description: >- HTTPS provider base. Host safety is proven by the credential service. dialect: type: - string - 'null' description: >- Registered rig dialect, or absent for a plain compatible gateway. The native Gemini and Ollama APIs take none. max_output_tokens: type: integer format: int32 description: Model's configured maximum completion length, including reasoning. minimum: 0 additionalProperties: false Mintable: type: object description: >- An integration this run may request a short-lived credential for. Contains its identifier, never a stored credential or token. required: - name - integration properties: integration: type: string description: >- The integration the broker mints for. The workspace is server-derived. name: type: string description: The placeholder name the fleet references. NetworkPolicy: type: object description: >- Allowed hosts for HTTP tools. An empty `allow` list blocks these requests. Sandbox network access also depends on the runner's network policy and registry allowlist. required: - allow - read_only - read_post_paths properties: allow: type: array items: type: string description: Exact hostnames HTTP tools may reach. read_only: type: boolean description: >- Restrict tool requests to safe reads, keeping a credential from crossing to a host other than its own declared endpoint. read_post_paths: type: array items: type: string description: Exact prefixes where a read-only tool may use POST for a query. RepositoryBinding: type: object description: The repositories a run is bound to, and how it may use them. required: - repositories - access - base_branch properties: access: $ref: '#/components/schemas/RepositoryAccess' description: Whether the run may write to them. base_branch: type: string description: Branch a write is based on. repositories: type: array items: type: string description: Repositories the run may reach. ContextRole: type: string description: Saved conversation role. Only the server can assign system instructions. enum: - user - assistant Pricing: type: object description: Model and runtime rates used to bound this attempt. required: - input_nanos_per_million - output_nanos_per_million - runtime_nanos_per_second properties: input_nanos_per_million: type: string description: Fresh input cost per million tokens. output_nanos_per_million: type: string description: Output cost per million tokens. runtime_nanos_per_second: type: string description: Runtime cost per second. HttpRequestRule: type: object description: >- An allowed HTTP method and path. Locked fields must match. When `permitted_fields` is present, only locked and listed fields are allowed; query strings are refused. When absent, other fields and query strings are allowed. required: - method - path - path_match - json_fields properties: json_fields: type: array items: $ref: '#/components/schemas/HttpJsonFieldRule' description: Fields whose values the rule locks. method: $ref: '#/components/schemas/HttpMethod' description: The method this rule admits. path: type: string description: The path this rule admits. path_match: $ref: '#/components/schemas/HttpPathMatch' description: Whether `path` is matched exactly or as a prefix. permitted_fields: type: - array - 'null' items: type: string description: >- Additional allowed field names. An empty list permits only locked fields. When omitted, other fields and query strings are allowed. InferenceApi: type: string description: The provider API rig uses for this configured model. enum: - chat - responses - messages - gemini - ollama RepositoryAccess: type: string description: Whether a bound repository may be written or only read. enum: - read - write HttpJsonFieldRule: type: object description: One required top-level JSON field, with exactly one expected value set. required: - name properties: boolean_value: type: - boolean - 'null' description: Expected boolean value, when the rule locks a boolean. name: type: string description: The field name the rule locks. string_value: type: - string - 'null' description: Expected string value, when the rule locks a string. HttpMethod: type: string description: HTTP methods allowed by a server-defined request rule. enum: - get - head - post HttpPathMatch: type: string description: Whether a request path must equal the authored bytes or begin with them. enum: - exact - prefix securitySchemes: RunnerBearerAuth: type: http scheme: bearer bearerFormat: agt_r description: Runner token beginning with agt_r, returned once by POST /v1/runners ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.