Necto platform API

List governed agents

Not yet available.

Responses

Compile a profile and return its artifacts

Not yet available.

Request

Body: application/octet-stream

Responses

Open a pull request changing this agent's profile

Not yet available.

Parameters

agentId *

path · string

Request

Body: application/json

Responses

Compile a `kind: Task` and check that it narrows, never widens

A task compiles to a restriction set intersected with the target agent's already-approved compiled artifacts. Because a task widens no compiled artifact, a narrowed result needs no approval. If the intersection is not exactly what the task requested, compiling is refused with the offending field, never a coerced narrowing.

Request

Body: application/octet-stream

Responses

List scheduled tasks

Every kind: Task apply that carried a schedule. A one-shot task, one with no schedule, runs once and is never listed here, the same way nectoctl apply -f necto.yaml never lists a run.

A machine caller reads only the scheduled tasks of the one agent its operation is scoped to, whether or not it names that agent; naming another agent is refused. A human caller reads every scheduled task.

Parameters

agentId

query · string

The agent whose scheduled tasks to list. Optional for a machine caller, whose own operation already scopes the answer; naming another agent is refused. A human caller reads every agent's tasks.

Responses

List releases awaiting review

Not yet available.

Responses

Compile a profile and open a release

Compiles, opens a release awaiting approval, and stops; it never changes a running agent. via: pull_request is the default and the required carrier in a customer production environment; via: direct records the profile in Necto's release store instead of a git commit, and is refused with 422 there. imageDigest is the prebuilt artifact the release binds -- an E2B template build id (a UUID), built outside this process -- and the governed run starts its sandbox from it. Optional only for a release that binds no artifact; a governed run refuses such a release rather than starting from a stage's default template. A template name, alias or tag is refused: it is movable, and a rebuild would change what runs with no new release. An OCI image digest is refused until an OCI path exists; only E2B template ids are accepted today.

A release for an agent the platform does not hold registers it from this profile: its diff is computed against a profile that grants nothing, so every source, tool, egress destination and authority change shows as added. A release for an agent the platform holds is diffed against the profile that agent's last release registered.

Request

Body: application/json

Responses

The compiled policy diff

Computed on compiled artifacts, not on file text. A formatting-only change returns noPolicyChange: true with an empty changes array. The release's own approval window is approvalExpiresAt, and the recorded standing approval is rendered beside the diff with its own expiresAt when one is recorded and not revoked, so a client can warn before either lapses and renew it while the window admits a second approval.

Parameters

releaseId *

path · string

Responses

Required-test results for this release

Parameters

releaseId *

path · string

Responses

Approve or reject the compiled diff hash

The approver approves a hash, not a description. The request carries diffHash; if it no longer matches the release's current hash the approval is refused with 409. Refused with 409 when a required test failed, or when a citation no longer resolves.

Parameters

releaseId *

path · string

Request

Body: application/json

Responses

Revoke the release's standing Slack approval

Any human holding approval authority for this agent may revoke, and the act is recorded. Revoking is never harder than granting, so the grant's original approver is not required. Every standing grant the release's current diff hash bounds is revoked, never only the latest one; the revocation is checked at the next scheduled mint and never interrupts a send already in flight (the named lag). The grants are not edited: the revocation stands beside them. A machine principal may never approve or revoke.

Parameters

releaseId *

path · string

Responses

List the deployment's applications

Every application this deployment holds, in creation order. The tenant is the deployment's own; no request field selects it, and another customer's applications are never listed.

Responses

Register an application

The application is the primary customer object. One application keeps one stable identity across dev, stage and prod; this route registers that identity, and every environment, plan, deployment and record below keys on it. The body names the application and the source it is created from — one of the four accepted sources. The field set is closed: there is no field for code, a credential or persistent data, and an unexpected field is refused rather than ignored. The tenant is the deployment's own and never a request field; the creator is the assertion-resolved subject, never a body field.

Request

Body: application/json

Responses

Read one application

One application by its stable identity, or 404 when this deployment holds none — including an application of another customer, which is not readable through this deployment's store.

Parameters

applicationId *

path · string

Responses

Read the managed state one application environment owns

One logical database and role, bucket and queue per application environment, each with its own state and its own credential reference. Identifiers only — no field carries a credential value and no field carries payload content. The environment is the deployment's own selection; an environment the application holds no state for answers an empty list. Another customer's application is not one this deployment holds, and its read is a 404.

Parameters

applicationId *

path · string

environment *

query · dev, stage, prod

Responses

Set up the managed state one application environment owns

The platform derives every name and reference; the request names only the environment. The logical database and role, bucket and queue names, and their credential references are the application-environment derivation's, never body fields. Setup is per service: while a provider does not answer, that service's state is recorded failed, never reported as success, and no credential is issued for it. A body field outside the closed set is refused rather than ignored. The tenant is the deployment's own; no request field selects it.

Parameters

applicationId *

path · string

Request

Body: application/json

Responses

Record a secret's reference

The value is held by the secret manager; the platform records a reference. The body carries the secret's name and value exactly once; the answer carries the reference the platform derived from the tenant, the application, the environment and the name, and never the value. No record the platform writes holds a value. A blank name or value is refused rather than defaulted. The tenant is the deployment's own; no request field selects it.

Parameters

applicationId *

path · string

Request

Body: application/json

Responses

Read the application's plan versions

Every plan version this application holds, oldest first. A version is immutable and identified by a content hash over the tenant key, the plan and its parent, so reading one back is reading what was recorded — never a later correction. provenance states, per plan field, whether the winning value came from detection or an explicit value. The tenant is the deployment's own and no request field selects it; another customer's application is not one this deployment holds, and its read is a 404.

Parameters

applicationId *

path · string

Responses

Detect a plan and record its version

Detection produces the visible, editable plan; the plan grants no authority. The application's registered source selects the construction path: a repository or template is detected through the adapter's closed input contract, a Dockerfile through the minimal read, and a prebuilt image skips detection. A key outside a closed contract, a language outside the fixture-tested set, and a detection that does not resolve to one plan are all refused rather than guessed; support is claimed per tested fixture only. saved is the saved project setting level; a field no level supplies is a refusal, never a default. The resolved plan is minted as an immutable version and answered with its per-field provenance. A detection resolving to the plan the application already holds answers with that version and records nothing new. The tenant is the deployment's own and no request field selects it.

Parameters

applicationId *

path · string

Request

Body: application/json

Responses

Correct the current plan version

A correction is a new immutable version, never a mutation of the one it corrects. The body's values is the closed necto.app.yaml schema — the correctable plan fields. A key outside it, toolchain and source included, is refused as unknown, and customer_id is refused like any other unknown key because the deployment supplies the tenant key, never a request. Every field the correction does not set keeps the value and the provenance it had; every field it sets carries the entered level. The corrected plan must differ from the current version: identical content is the same version, refused rather than recorded as a second one. The corrected version's parent is the current version, so a correction never forks the lineage. An application with no recorded plan has nothing to correct and answers 404.

Parameters

applicationId *

path · string

Request

Body: application/json

Responses

Read the application's graph and default guardrails

The read-only graph and the default guardrails, resolved for one application's accepted plan version. Every field carries the source it came from and the accepted plan version it was read at. The plan is topology only: a graph field is never compiled into a guardrail, so a tool, source, destination or credential appears only where the governed profile declares it. The placement is computed from the accepted plan's requested tier and the governed profile, never customer-forced. A refusal — a conflicting placement or a governed profile that does not compile — is visible in refusals with the policy decision's own reason and safe metadata, never a generic application error. The tenant is the deployment's own; another customer's application is a 404.

Parameters

applicationId *

path · string

Responses

Deploy the accepted plan to dev

A dev deployment gets an automatic record; no approval. The accepted plan version is named by its content hash and reconciled into the application environment's resources: standard components become restricted Kubernetes resources and governed components runtime start requests. Placement is computed by the platform — the namespace from the tenant, application and environment, and the tier from the accepted plan and governed profile — and neither is read from a body field. The governed profile hash and the compiled-artifact hashes on the record are the platform's own derived values. A deployment whose governed profile or compiled artifacts differ from the environment head record's is refused without an approval; the deployment-approval path is not built yet. Nothing reaches a cluster here; the live adapters are a later ticket.

Parameters

applicationId *

path · string

Request

Body: application/json

Responses

Open a promotion request to the next environment

One hop at a time, dev to stage to prod; skipping a stage is a refusal, never a warning. The request carries only an image digest, an accepted plan version and identifiers — there is no field that could carry a credential or persistent data, and none is accepted. The governed profile and compiled-artifact hashes the approvers sign are the platform's own derivation from the application's registered governed profile, never request fields. The tenant is the deployment's own; no request field selects it. The target environment's namespace is derived by the platform from (customer, application, environment) and never read from this body; the runtime tier is computed from the requested tier and the governed profile, never posted. Both seams refuse fail-closed with 503 while unwired.

Parameters

applicationId *

path · string

Request

Body: application/json

Responses

Approve or reject a promotion, bound to the combined hash

The approver approves a hash, not a description. Two distinct, assertion-resolved approvers are required before a promotion may execute. The requester cannot approve their own promotion; a subject has one decision per promotion; an approval naming anything but the promotion's current combined hash is refused. The approval records the target environment's head deployment record at decision time, and expires with the deployment's approval window.

Parameters

promotionId *

path · string

Request

Body: application/json

Responses

Execute an approved promotion

Executes only when two distinct assertion-resolved approvals bind the promotion's combined hash, neither has expired, the target environment's head deployment record is still the one the approvals recorded, and a private-e2b target's placement gate is proven. The platform recomputes the governed profile hash and the compiled-artifact hashes from current state: when they differ from what the approvals signed, the approval is void and nothing is recorded as deployed. The new deployment record lands through a compare-and-swap on the target head: two concurrent executes succeed exactly once. No override parameter exists.

Parameters

promotionId *

path · string

Responses

The application's collaboration mutation journal, newest first

Every mutation records the actor and the resulting version. The append-only journal is read one application at a time, newest first, tie-broken by insertion order the way the durable backend's rowid does. Every field is an identifier — subject, object id, version — never a comment body, prompt or payload. The deployment's own tenant key is carried on the record and is never selected by the request. A caller whose assertion verified and for whom Necto holds no authority record is refused 403; a machine principal is refused by its own client-principal record.

Parameters

applicationId *

path · string

Responses

The application's version history, derived at read time

Read-only by shape. The history is derived at query time from the stores that already own the rows — the accepted plan versions, the deployment records, the release records and the run registry — and writes nothing. Every entry carries the anchor kind, the identifier its store knows it by, the time and the actor where the store has them. A plan version has no clock and no actor on the artifact; a run record has no actor; the entry reports the absence rather than inventing one. A plan version's parent is carried by hash. The plan store has no application key, so the tenant's plan versions are part of every application read; a version is not attributed to one application by a key that does not exist. The deployment store's only list-shaped read is the record in force per environment, so the history lists the current head and not every superseded record. The tenant is the deployment's own and is never taken from the request.

Parameters

applicationId *

path · string

Responses

Grant a collaboration role on an application

The first administrative surface. The caller resolves in Necto's authority store — the operator is the first administrator — and the granted subject is named by its issuer and subject, never by an email address. The grant is per application; the store is bound to the deployment's own tenant key, so no request, claim or header selects another. Every grant appends a role_grant record to the mutation journal before the store moves. An approving grant alone does not approve: approval still reads the authority record.

Parameters

applicationId *

path · string

Request

Body: application/json

Responses

Revoke a collaboration role on an application

Revoking is never harder than granting. The caller resolves in Necto's authority store; the grant is removed, never edited, and the revocation appends a role_grant record to the mutation journal. A revocation with no grant in force is refused 409: every recorded revocation is attached to the version it removed.

Parameters

applicationId *

path · string

subject *

path · string

The stable subject identifier of the grant to revoke

issuer *

query · string

The issuer half of the grant's key; a subject is only unique within its issuer

Responses

Clone an application's plan version into a new application

A clone is a new application carrying the source plan version's topology only. The clone's new plan version is minted field by field from the source plan's ten topology fields, with the source version hash as its parent; the source version, application and repository are unchanged. No approval, deployment, release, run, role grant, credential, secret or managed-state resource is carried: none has a plan field or a parameter to travel through, and each environment of the clone resolves its own secrets. One plan_version cloned record is appended to the mutation journal, naming the actor, the source version hash and the clone's version hash; a record the journal refuses leaves no clone. The source version is read through this deployment's own tenant-keyed plan registry, so another customer's version is not found — refused 404, never cloned. The caller needs an editing collaboration grant on the source application; without one the clone is refused 403. The field set is closed: a field outside it is refused rather than ignored, and a blank or malformed field is refused 422, never a 500.

Parameters

applicationId *

path · string

Request

Body: application/json

Responses

List one application's comments, newest first

One row per comment, and a redacted comment carries no body. Each item is the newest row of one comment: the identifier, the application, the anchor, the actor and the time of that newest row, whether it is a redaction, and how many revisions the store holds. A live comment carries the newest body; a redacted comment carries no body at all, because a redaction hides the body rather than overwriting it. The optional anchorKind and anchorId filters narrow the list to one anchor, and both are needed. The read needs the caller's viewing grant on this application: no grant is 403, and the store is bound to the deployment's tenant key, so another customer's comments are never listed. An unknown anchor kind is refused 422 rather than answered with a whole application's comments.

Parameters

applicationId *

path · string

anchorKind

query · plan_version, deployment, run, policy_version

The anchor kind to filter by; anchorId is needed beside it.

anchorId

query · string

The anchor's own identifier to filter by.

Responses

Record a comment on an application

The body is user content and enters no trail. The caller needs the editing grant on this application: a viewing grant alone is refused 403, and no grant is refused 403 before anything is recorded. The actor is the caller's resolved subject key and the time is the platform clock, never request fields. The comment store appends the row and writes the one comment journal record; the route writes no second record. The response carries the recorded comment's identifiers and never the body: the body is read back through the list route, and no comment body enters the journal or the evidence timeline. A comment id the store already holds is refused 409: an edit is a revision, never a second creation.

Parameters

applicationId *

path · string

Request

Body: application/json

Responses

Redact a comment

A redaction appends a revision; it never mutates or deletes one. The caller needs the editing grant on this application: a viewing grant is refused 403, and no grant is refused 403 before the comment is read. The actor is the caller's resolved subject key and the time is the platform clock, never request fields. The store appends one redaction row carrying the version of the revision it hides; the hidden revision stays in the store and the journal keeps both versions, never overwritten and never deleted. The response carries the new row's identifiers — including the redacted revision — and never a body: a redacted body enters neither the journal nor the evidence timeline. A comment this deployment does not hold is 404, and a comment already redacted is 409: a redaction is final, and a later revision cannot put the body back. A comment of another application in this tenant is not this application's: the editing grant is per application, so the redaction never reaches it.

Parameters

applicationId *

path · string

commentId *

path · string

The comment's own identifier, stable across its revisions.

Responses

The application's run budget for its current window

The per-application run budget: the cap on runs in one fixed window, the window's own count and the runs remaining. The claim that enforces it happens at run admission, in the same step as the run's own registration, so a start past the cap refuses before any sandbox starts and records no run. Runs are the counted dimension; a spend dimension joins when the metered instrument records it. No budget recorded is a 404: the read answers the record and never a default cap. The tenant is the deployment's own; no request field selects it.

Parameters

applicationId *

path · string

Responses

The agent catalogue card

Denied requests are returned alongside successful runs, not behind a filter.

Parameters

agentId *

path · string

Responses

What is usual for this agent, by release regime

The baseline a run is compared against: the documents, destinations, tool order, records-per-run and run-seconds the agent's release regimes have actually shown. A baseline is keyed to one agent, one compiled profile and one release, so a release opens a new regime instead of being reported as drift on release day; a prior regime's baseline is kept for comparison and never scores the next one. transitions names where one regime's baseline ended and the next began.

The four dimensions are facts, never a score. state is ready when the regime has enough observed history to compare against, and insufficient_volume when it does not: the state scores nothing, and the comparison carries no verdict rather than a low one. observedRuns is the number of the regime's finished runs the baseline summarises. Identifiers only: document ids, destination names and tool names, never content, passages, prompts or credentials.

Parameters

agentId *

path · string

Responses

Start a governed run

Returns identifiers only: no document text, no raw prompts, no credential values. The run is asynchronous; watch /runs/{runId}/timeline?watch=1 for the ordered TimelineEntry stream.

A registered machine client may start the run from a schedule tick by sending a trigger. The run then takes its input from the scheduled task the trigger names, records the tick on the run's timeline, and carries the trigger on the card's run summary. A caller that is a person, a trigger that names no task of this agent, an instant that is not a tick of the task's schedule, or a tick outside its own period is refused, and nothing starts. A tick is outside its own period when it is more than one minute after the current instant, or more than one period of the task's own schedule plus a short transport margin before it: the tick is stale once the next tick exists. A tick refused as stale is recorded as a skipped tick on the agent's schedule stream, while a tick refused before its period is due is recorded on that stream under the distinct kind schedule_refused, without a tick key, so the refusal does not pre-decide it. A repeated trigger key starts no second sandbox: the response carries the run the key already names.

Parameters

agentId *

path · string

Request

Body: application/json

Responses

The agent's schedule stream, newest first

Every tick this agent's scheduler recorded, newest first: the accepted ticks beside the ticks that did not run. An accepted tick is the run's own schedule_fired entry; a stale tick is the keyed schedule_skipped with reason refused; a tick refused before it could have run is the distinct schedule_refused with reason future and no key; the remaining skips carry contained, overlap, failed or missed. Each entry carries its tick key where one exists, its task id and its scheduled instant beside the instant the platform recorded it. A human caller with authority for the agent reads the stream; a machine client and a workload-originated call are refused, because the scheduler reports ticks and never reads them back. An unknown agent is refused like the card. limit defaults to 50 and a value outside 1 to 200 is refused by name rather than clamped.

Parameters

agentId *

path · string

limit

query · integer

How many of the newest entries to return. Default 50; a value outside 1 to 200 is refused rather than clamped.

Responses

Record a tick the scheduler observed as missed

Machine-only. A scheduler reports a tick it did not fire because it was past its grace window. The API recomputes the trigger key from the task id and the scheduled instant and records a skipped tick with reason missed on the agent's schedule stream. A key that already names a run or a skipped tick is a no-op: the scheduler's boot look-back reports every past-grace tick it can see, and the API is what de-duplicates. A caller that is a person, or a request that does not name a missed tick of this agent, is refused.

Parameters

agentId *

path · string

Request

Body: application/json

Responses

Mint and execute one standing-approved send

The scheduled-run send surface. A scheduled run mints one fresh, ordinary, single-use ActionEnvelope under the standing approval it names and executes it through the existing single-use consumption path: no second consumption model, no reusable envelope, and no adapter change. The grant approves one channel and one message schema; the envelope names the grant in approvalRef and the grant's approver in caller, so the adapter's existing per-call revalidation is the check the send passes. Every refusal the standing-approval rules define is this route's own refusal, never a 500: an unknown grant is 404; a revoked grant, a channel outside the grant, a URL host the profile's allowlist does not admit and a tool the compiled allowlist does not permit are 403; a release change that voided the grant is 409; an expired grant is 410; a payload outside the approved schema, a field over its length cap, a title or price carrying URL-like text, or a url that is not exactly one absolute https URL is 422; and a mint over the per-run or per-day cap is 429. A workload-originated call is authorised by its own run. The console's workload relay verifies a DPoP-bound workload token and mints the assertion with the verified workload claims beside the sandbox instance id as sub: agent_id, run_id, tool and audience. A call carrying those claims is refused on every route but this one, and on this route it is refused unless that run exists, is live, was started by Necto for this agent, runs in that instance, the tool is one the run delivered, the instance's workload tokens have not been revoked by a stop, this request's runId and tool are the assertion's, and the forwarded audience is the verified tool's own per-tool audience necto:<agentId>:<tool>. The revocation is read from the deployment's own revocation list by the instance the assertion names; a deployment with no such list to read, or a list that cannot be read, refuses the call rather than assuming the instance is not revoked. Only the run's own workload call may spend the standing approval. A session assertion is refused here with 403, whatever authority it holds: a human approves each send through the ordinary approval surface. The per-run cap is counted on the run the relay verified, never on a value in this request, so a request naming another run is refused and cannot reset it.

Parameters

agentId *

path · string

Request

Body: application/json

Responses

Record one destination a governed run's egress refused

The relayed refusal report. A newly onboarded agent starts with zero egress permissions, so every destination it tries is refused; the sandbox reports the refused destination's identifiers and the platform records them for the customer's review. Identifiers only: the host, the port and the protocol, the run's governed-component identity and the run, the platform's own instant and the bounded attempt counter; no payload, content or capture field exists. A workload-originated call is authorised by its own run. The console's workload relay verifies a DPoP-bound workload token and mints the assertion with the verified workload claims beside the sandbox instance id as sub. A call carrying those claims is refused on every route but the relayed routes, and on this route it is refused unless that run exists, is live, was started by Necto for the path's agent, runs in that instance, the instance's workload tokens have not been revoked by a stop, and the tool is one the run delivered. The revocation is read from the deployment's own revocation list by the instance the assertion names; a deployment with no such list to read, or a list that cannot be read, refuses the call rather than assuming the instance is not revoked. The body's field set is closed: host, port and protocol only, and an unexpected key is refused. The tenant key, the run's governed-component identity and the run come from the deployment and the verified claims, never from this body: the body carries no runId, so a caller cannot file a refusal under another run. A repeat observation coalesces into its row's counter up to the platform's cap, and a new destination past the run's cap is not recorded: the answer is 202 with recorded: false and reason: flood-cap, and the run is not failed. The cap value is set by the change that lands the row, never by this document.

Parameters

agentId *

path · string

Request

Body: application/json

Responses

One run, end to end

Identifiers and decisions only: no document text, no raw prompts. Dropped candidates are included with their reason; a timeline showing only what was retrieved hides the control that was exercised. watch=1 upgrades the response to a Server-Sent Events stream, one TimelineEntry per event; omit it for the current snapshot. A workload-originated read is authorised by its own run: the console's workload relay mints the assertion with the verified workload claims beside the sandbox instance id as sub, and a call carrying those claims is refused on every route but this one and the actions route. The read is refused unless that run exists, is live, was started by Necto for the assertion's agent, runs in that instance, the instance's workload tokens have not been revoked by a stop, and the tool is one the run delivered. The revocation is read from the deployment's own revocation list by the instance the assertion names; a deployment with no such list to read, or a list that cannot be read, refuses the read rather than assuming the instance is not revoked. A session assertion is decided exactly as before. Every entry carries its own evidence class: semantic for a kind the four behavioural dimensions read, infrastructure for every other kind. An entry presented as semantic agent evidence is checked by require_semantic before it is presented, and a refusal is the named 409 whose detail names the kind.

Parameters

runId *

path · string

watch

query · boolean

Stream new entries as Server-Sent Events instead of returning a snapshot

Responses

One run's chat stream, as AG-UI events

The small optional chat surface, behind a Necto-owned interface: AG-UI's event names on Server-Sent Events, so the protocol adapter may be replaced without changing the application or the evidence models. Every event is derived from the run registry and the run's own timeline: run state is the registry's own rows, and tool activity is the run's own credential-injection entries. Identifiers and decisions only: no message text, no tool arguments and no raw chain-of-thought is emitted or stored, because the platform stores none. The caller is authorised by the same record every run read uses: a caller Necto holds no authority record for is 403, and a run Necto never registered is 404 rather than an empty stream.

Parameters

runId *

path · string

Responses

One run's behaviour against its regime's baseline

The same four dimensions for one run — documents read, destinations contacted, tools and their order, records opened and seconds elapsed — plus the comparison against the baseline of the regime that run belongs to, as it stood before the run started. Only that regime's runs that finished before this run started count, so a later or unfinished run never widens the baseline an earlier run is compared against. A run is never compared with another regime's baseline or with itself, and the response names the regime it was compared against.

Refused attempts are observations, never absences: an attempt the platform refused is returned with the rule that refused it. state is ready when the regime has enough observed history to compare against, and insufficient_volume when it does not: the state scores nothing, and the comparison carries no verdict rather than a low one. Identifiers only: document ids, destination names and tool names, never content, passages, prompts or credentials.

Parameters

runId *

path · string

Responses

Whether the calling workload instance's tokens are revoked

The console workload relay's own read, before it forwards a relayed request. The instance is the one the verified console workload assertion names as its subject; the tenant is the deployment's own and is never taken from a claim or a request value. The read takes no path or query parameter, performs no action and reads no run: it answers for a stopped instance too, so a revoked presentation is refused however fresh its proof is. Answers {"revoked": false} while the instance's tokens are live, and {"revoked": true} once a stop has revoked them. A caller that is not a workload assertion is refused: a human session and a machine principal are 403. A deployment whose revocation list is absent or unreadable is answered 503, so the relay forwards nothing rather than a presentation nobody checked.

Responses

Release a previous version of this agent

Not yet available.

Parameters

agentId *

path · string

Request

Body: application/json

Responses

Whether this agent may use a tool, without invoking it

Answers nectoctl auth can-i. Evaluates the agent's compiled action allowlist for the calling identity; never invokes the tool and never mutates anything.

Parameters

agentId *

path · string

tool *

query · string

Responses

Stop the agent immediately

Not a release. No pull request, no approval, no build in this path. Safe to call on an already-stopped agent; still recorded.

Parameters

agentId *

path · string

Responses

Revoke the agent's credentials upstream

Invalidates upstream, verified against the upstream rather than against Vault's own view of its lease. Distinct from stop: nothing revokes a Vault lease when a workload dies.

Parameters

agentId *

path · string

Responses

Export a review bundle for a period

The export is itself an action, recorded in the timeline. The bundle carries identifiers and decisions, never content. Assembled in the request, from what the evidence store holds, so it returns with the identifier. complete is false when the period predates the retention cutoff: older entries may be purged.

Parameters

agentId *

path · string

Request

Body: application/json

Responses

The caller's own identity and approval authority

Derived from the audience-bound assertion, never from the browser. Answers nectoctl auth whoami, and is distinct from /agents/{agentId}/authority/check, which answers for an agent rather than for the caller.

Responses

This deployment's federation registry records

Console service identity. The console server reads the committed federation registry live over its existing east-west path and keeps no copy of its own: the upstream issuers, the named endpoint hosts and the allowed verification bases this deployment's records hold, so a registry record and a console provider config cannot disagree silently. The read is the console server's own call, never a signed-in person's: an assertion that is not the console's service identity (iss = the deployment's console issuer, sub = necto-console) is refused. Tenant- and deployment-scoped: the records are the deployment's customer id's, read from the deployment and never from a request, claim or header. Identifiers and display fields only, never a secret: no client credential, domain or endpoint path is in the record or the answer. limit defaults to 200 and a value outside 1 to 500 is refused by name rather than clamped.

Parameters

limit

query · integer

How many records to return. Default 200; a value outside 1 to 500 is refused rather than clamped.

Responses

Problem

title *

string

status *

integer

detail

string

field

string

The offending profile field, for a 422

requested

string

What the caller asked for, on a kind: Task widening refusal from POST /tasks/compile: the single source, tool or authority value named by field.

granted

string

What the target already grants, alongside requested: the profile's own authority for a widened authority, or its comma-joined data/tools list for a source or tool the profile does not list.

AgentSummary

agentId

string

name

string

owner

string

purpose

string

environment

string

authority

read_only, draft_only, write_reversible, write_external

currentVersion

string

CompiledProfile

The compiled artifacts, each content-addressed, plus the containment plan added on acceptance.

profileHash

string

runtimeConfig

object

retrievalPermissions

object

credentialScopes

object

actionAllowlist

object

requiredTestMatrix

object

evidenceHeader

object

containmentPlan

object

Five questions for this agent: who may trigger containment, what triggers it, what changes immediately, what evidence remains, who can restore service. Declaring a plan is not evidence that containment works.

artifactHashes

object

ReleaseSummary

releaseId

string

agentId

string

diffHash

string

state

awaiting_approval, approved, rejected, void, expired

expiresAt

string (date-time)

Unapproved releases expire after seven days

via

pull_request, direct

How the profile text was recorded. direct is refused when the calling context's environment is production.

imageDigest

string

The prebuilt artifact the release binds. Present only for a release that binds one; absent reads as absent rather than as a blank a reviewer might take for a value.

PolicyDiff

diffHash *

string

noPolicyChange *

boolean

True for a formatting-only change

approvalExpiresAt *

string (date-time)

The release's own approval window: the instant the release stops being approvable, computed by the platform from the recorded release, never by the caller. Present on every diff read, after the window passed included.

changes *

array of object

standingApproval

StandingApprovalProposal

standingApprovalGrant

StandingApprovalGrant

standingApprovalRevoked

StandingApprovalRevoked

StandingApprovalGrant

The standing approval the release has recorded, beside the diff: the grant the next scheduled run mints under when one is spendable, otherwise the release's latest recorded grant, whose expiry has passed. Present when a grant is recorded and not revoked; absent when the release has no grant, and replaced by standingApprovalRevoked when the recorded grant was revoked. A grant past its own expiry is still rendered, because the expiry is the fact a client warns on and the approval route's own refusal is the enforcement.

grantId *

string

The grant the next scheduled run mints under when one is spendable, otherwise the release's latest recorded grant.

channelId *

string

The one channel the grant is scoped to

approver *

string

The human whose approval the grant records

grantedAt *

string (date-time)

The instant the grant was recorded

expiresAt *

string (date-time)

The instant the grant stops being usable. A second approval before the release's own window passes records a fresh grant; after it passes, renewal is a new release.

StandingApprovalProposal

What the approver would approve beside the diff: the release's agent's scheduled task deliver alias resolved to one Slack channel id by the deployment's composition, never a request value. Absent when the deployment registers no channel for the alias, the agent has no scheduled task, or the release's profile does not compile write_external.

channelId *

string

The one channel id the deployment resolved for the deliver alias. The approver echoes it back; the API refuses a value that is not this one.

messageSchema *

array of string

The one message schema the grant approves

perRunCap *

integer

The per-run cap, never a request value

perDayCap *

integer

The per-day cap, never a request value

maxExpiryDays *

integer

The expiry ceiling; a shorter expiry is the approver's choice

StandingApprovalRevoked

The recorded revocation of the release's standing approval, beside the diff. Present instead of standingApproval when the release's recorded grant has been revoked, so a client that does not know this field shows no approval rather than one that still looks live.

grantId *

string

revokedBy *

string

The human whose act ended the grant

revokedAt *

string (date-time)

StandingApprovalRevocation

The recorded revocation: one entry per grant the release's current diff hash bounds, each naming the human whose act it was. The grants are not edited and not deleted: these records stand beside them, and the next mint is refused from revokedAt on.

releaseId *

string

grants *

array of object

RequiredTestResult

name

retrieval_scope, denied_access, expired_credential, blocked_egress, output_format

passed

boolean

artifactUrl

string

The stored output. A pass without an artifact is a claim.

blocksRelease

boolean

Always true on failure

ApprovalRecord

releaseId

string

diffHash

string

decision

approve, reject

approver

string

party

customer, necto

The side of the two-approver rule the resolved authority record named when the decision was made. A widening release needs one customer and one necto approval by two distinct subjects; a non-widening release is approvable by the customer's own security owner alone.

decidedAt

string (date-time)

requiresTwoParties

boolean

Whether the release widened egress or tool authority against the release the platform ran when the decision was made. true marks a decision that needs one customer and one necto approval by two distinct subjects; an absent field is a one-party decision. Forward-only: a previous build refuses a record that states true rather than reading one party as two.

fallback

boolean

Whether the decision is the Necto-operator fallback: the operator approves only while no customer security owner resolves for the deployment. The record names the fallback explicitly and never claims the customer's approval; its party stays necto. Forward-only: a previous build refuses a record that states true rather than reading the operator as the customer's approval.

reasonCode

not-needed, wrong-scope, test-failure, citation-gone, unsafe-change, other

A rejection's structured reason code, from the closed set. An approval carries neither a code nor a reason text. The text beside it is stored and never parsed for ids or commands. Forward-only: a previous build refuses a record that states one rather than reading a rejection as an approval.

reason

string

The rejection's free text, stored verbatim beside its code and escaped on render. It is never parsed for ids or commands. Forward-only: a previous build refuses a record that states one rather than reading an unreviewed word as the reason code.

CollaboratorGrant

One recorded collaboration grant: the application, the granted subject's issuer and subject, the role, the grant's content-hash version, the actor whose act it was and the time. Every field is an identifier — never a display name, an address or a claim. customerId is the deployment's own tenant key, recorded with the grant and never selected by the request.

customerId *

string

applicationId *

string

issuer *

string

subject *

string

role *

viewing, editing, deploying, approving, stopping

version *

string

The content-hash identity of the grant state the act produced or removed

actor *

string

recordedAt *

string (date-time)

ApplicationClone

One clone act's result, as identifiers only: the clone's new stable application id, its new plan version hash and the source version hash the clone is parented to. Never a plan, a secret or any copied content.

applicationId *

string

versionHash *

string

sha256:<hex> of the clone's new plan version

parent *

string

The source version hash the clone is parented to

CommentAnchor

What a comment is attached to, by identifier: the anchor kind and the anchor's own id. kind is a closed set — an unknown kind is refused rather than filed. The id is an identifier, never the object it names.

kind *

plan_version, deployment, run, policy_version

id *

string

Comment

One comment's newest row, as identifiers and a count. redacted is true when the newest row is a redaction; revisionCount is how many rows the store holds — a count, never a prior body. body is the newest revision's content and is present only for a live comment: a redacted comment carries no body. redacts is the version of the revision a redaction hides and is present only when redacted is true; the hidden revision stays in the store, never mutated or deleted. The actor is a subject identifier, never a display name, and at is when the newest row was recorded.

commentId *

string

application *

string

anchor *

CommentAnchor

actor *

string

at *

string (date-time)

redacted *

boolean

revisionCount *

integer

body

string

The newest revision's content; absent for a redacted comment, because a redacted body is never returned.

redacts

string

The version of the revision this row hides; absent unless redacted is true, because a live comment redacts nothing.

ApplicationBudget

applicationId *

string

runLimit *

integer

The cap on runs admitted in one window.

windowSeconds *

integer

The fixed window's length; a window is aligned to the Unix epoch, so the same instant maps to the same window everywhere.

windowStart *

string (date-time)

windowEnd *

string (date-time)

used *

integer

The runs claimed in this window.

remaining *

integer

The runs this window still admits, derived from the cap and the window's own count rather than carried beside them.

PromotionRequest

One promotion hop, as metadata only. There is no field for a credential or persistent data, structurally: promotion carries an image digest and an accepted plan version, never either.

promotionId

string

application

string

actor

string

The requester's assertion-resolved subject

fromEnvironment

dev, stage, prod

toEnvironment

dev, stage, prod

imageDigest

string

acceptedPlanHash

string

sourceRevision

string

detectorVersion

string

builderVersion

string

profileHash

string

The platform-derived content hash of the application's registered governed profile, or the explicit value none when none governs it. Never a request field.

governedRuntime

string

server-derived from the application's governed profile, never a request field; the private-e2b placement gate reads it

artifactHashes

array of object

The platform's own compiled-artifact hashes for the registered governed profile in the target environment, or empty when none governs it. Never a request field.

requestedTier

standard, governed

placementTier

standard, governed

The platform-computed placement

namespaceName

string

The platform-derived namespace for the target environment; supplied by the derivation seam, never by a caller.

tests

array of object

requestedAt

string (date-time)

combinedHash

string

What the two approvers bind: the combined deployment hash over the application, target environment, image digest, accepted plan and governed hashes.

PromotionApproval

promotionId

string

combinedHash

string

decision

approve, reject

approver

string

targetHead

['string', 'null']

The target environment's head deployment record id at decision time — what the approval vouched for alongside the hash.

decidedAt

string (date-time)

ApplicationSource

Where the application's code comes from — one of the four accepted sources. An identifier, never content: a repository location, a template identity, a Dockerfile location or a prebuilt OCI image addressed by immutable digest. No field here carries code, a credential or persistent data.

kind *

repository, template, dockerfile, oci_digest

reference *

string

The source's identifier: a repository location, a template id, a Dockerfile location, or a sha256:<hex> image digest — the immutable identity a prebuilt image is addressed by, never a tag.

Application

One application: the primary customer object, one stable identity across dev, stage and prod. Metadata only — the record names its source, never code or a credential. Every record carries the deployment's tenant key; no request field selects it.

applicationId *

string

name *

string

source *

ApplicationSource

createdBy *

string

The assertion-resolved subject that registered it

createdAt *

string (date-time)

ManagedService

One managed service's own state in one application environment: the logical resource name and the credential reference the platform derived. Identifiers only — no field carries a credential value and no field carries payload content. state is the platform's own word: provisioned, or failed when the provider did not answer — never reported as success.

environment *

dev, stage, prod

service *

postgresql, object_storage, durable_queue

state *

provisioned, failed

resourceName *

string

credentialRef *

string

recordedAt

string (date-time)

ApplicationServices

The managed state one application environment owns, verbatim from the platform: the three services' logical resource names and credential references, each with its recorded state. The environment is the deployment's own selection; another customer's application is not one this deployment holds.

applicationId *

string

environment *

dev, stage, prod

services *

array of ManagedService

ApplicationServiceSetup

The one field setup names: the environment to set up. The names and references are the platform's derivation, never body fields.

environment *

dev, stage, prod

ApplicationSecret

The secret's name and value, carried once. The value is held by the secret manager and never recorded, returned or echoed; the answer carries the reference instead.

environment *

dev, stage, prod

name *

string

value *

string

The value the secret manager holds, never recorded or echoed

SecretReference

What recording a secret answered: the secret's name and the reference the platform derived and the secret manager holds. The value is never in the answer and never in any record.

name *

string

reference *

string

ApplicationPlan

The visible, editable plan: topology only, never authority. No field grants a tool, source, destination or credential — necto.yaml remains the only authority source for governed components. The plan carries the deployment's tenant key; no request field selects it.

customerId *

string

The deployment's tenant key

source *

PlanSource

components *

array of PlanComponent

toolchain *

PlanToolchain

commands *

PlanCommands

network *

PlanNetwork

schedules *

array of PlanSchedule

resources *

PlanResources

dependencies *

array of string

destinations *

array of PlanDestination

runtimeTier *

standard, governed

The requested runtime tier; placement is computed later

PlanSource

The source revision and build context, or the digest that is the source for a prebuilt image — topology, never authority.

kind *

repository, dockerfile, oci_digest

revision

string

buildContext

string

imageDigest

string

sha256:<hex>; the immutable identity a prebuilt image is addressed by

PlanComponent

A component's name and kind, and the one profile identity a governed component carries — a name, never the compiled profile.

name *

string

kind *

web, api, worker, static

profile

string

PlanToolchain

The detector, builder and base-image identifiers. Identifiers, never measurements: synthetic adapter input records synthetic-adapter-input and claims no version.

detector *

string

builder *

string

baseImages *

array of string

PlanCommands

build *

array of string

start

string

PlanPort

port *

integer

protocol

string

PlanHealthCheck

path *

string

intervalSeconds *

integer

PlanNetwork

ports *

array of PlanPort

healthCheck

PlanHealthCheck

PlanSchedule

A command with no schedule is a worker; one with a cron expression is a schedule

name *

string

command *

string

schedule

string

PlanResources

Resources and scaling bounds

cpuCores *

number (double)

memoryMib *

integer

minInstances *

integer

maxInstances *

integer

PlanDestination

A declared external destination for a standard component — a bare host name, topology only. It grants no reachability and routes no traffic.

host *

string

ApplicationPlanVersion

One immutable plan version: the plan, its content hash and parent, and the winning source of every field. The hash is minted from the tenant key, the plan and the parent, so a version is never re-labelled and a correction is a new version, not a change to this one.

applicationId *

string

versionHash *

string

sha256:<hex> over the tenant key, the plan and the parent

parent

string

The version this one corrects; absent for the first version

plan *

ApplicationPlan

provenance *

object

Every plan field's winning source, keyed by the plan's field name — the plan's own precedence display.

PlanFieldProvenance

Where a field's winning value came from, verbatim from the plan's own precedence: the explicit repository file, the saved project setting, or the detector default. Every displayed field carries one.

ApplicationPlanDetection

The detection input. The application's registered source selects the construction path: adapterInput is the detector's output for a repository or template source, dockerfile is the file's text for a Dockerfile source, and a prebuilt image has neither — its digest is the source and the build is skipped. The detector output is adapter input, never the public schema: it is read against a closed contract, and a key outside it is refused rather than ignored. saved is the saved project setting level, read against the closed necto.app.yaml schema.

adapterInput

object

The detector's output for a repository or template source, read against the adapter's closed contract — never the public schema and never persisted as such.

dockerfile

string

The Dockerfile's text for a Dockerfile source; at most the minimal read (FROM, EXPOSE, CMD) resolves a value, and anything ambiguous is refused.

saved

object

The saved project setting level, read against the closed necto.app.yaml schema; an unknown key is refused.

ApplicationPlanCorrection

A customer correction of the current plan version. values is the closed necto.app.yaml schema — the correctable plan fields. A key outside it is refused as unknown; toolchain and source are deliberately not correctable, and customer_id is refused like any other unknown key because the deployment supplies the tenant key.

values *

object

The closed necto.app.yaml value set

ApplicationGuardrails

The read-only graph and the default guardrails for one application's accepted plan version. Every field states the source it came from and the accepted plan version it was read at: a graph field's source is the plan's own per-field provenance, a guardrail field's source is the governed profile (or default when none governs), and the placement's source is computed. The plan is topology only and grants no authority — no graph field is compiled into a guardrail.

applicationId *

string

planVersion *

string

The accepted plan version hash every field was read at

profileHash

string

The governed profile's content hash when one governs the application; absent when none does

fields *

array of GuardrailField

refusals

array of GuardrailRefusal

GuardrailField

One graph or guardrail field, its value, the source the value came from and the accepted plan version it was read at.

name *

string

The plan field's camelCase name for a graph field, or the guardrail's own dotted name (guardrails.actionAllowlist, guardrails.egressAllowlist, guardrails.credentialScopes, placement)

value *

any

source *

string

The value's winning source: the plan's per-field provenance level for a graph field, governed profile for a compiled guardrail, default when no profile governs, or computed for the placement. Never a plan field standing in for authority.

version *

string

The accepted plan version hash this field was read at

GuardrailRefusal

A refusal the read made visible: the field it concerns, the policy decision's own reason, its safe metadata and the accepted plan version it was read at — never a generic application error.

name *

string

reason *

string

The policy decision's own named reason

field

string

The profile field a compile refusal names

detail *

string

version *

string

ApplicationDeployment

One deployment of the application's accepted plan. The plan version is named by its content hash and the image by immutable digest; the environment is the deployment's dev environment, and the governed profile hash and compiled-artifact hashes on the record are the platform's own derived values, never body fields.

acceptedPlanHash *

string

The accepted plan version's content hash

imageDigest *

string

sha256:<hex>; the built image this deployment runs

tests

array of object

Test-name and artifact-URL identifier pairs

DeploymentRecord

Every deployment's automatic record: metadata only — never source, prompt, response, secret or payload content.

deploymentId

string

actor

string

application

string

environment

dev, stage, prod

sourceRevision

string

detectorVersion

string

builderVersion

string

acceptedPlanHash

string

imageDigest

string

tests

array of object

Test-name and artifact-URL identifier pairs

recordedAt

string (date-time)

outcome

string

profileHash

string

artifactHashes

array of object

AgentCard

The agent card's field set is fixed

agentId

string

owner

string

purpose

string

dataSources

array of string

allowedTools

array of string

environment

string

currentVersion

string

currentPolicyHash

string

recentRuns

array of RunSummary

deniedRequests

array of DeniedRequest

Returned alongside runs, never behind a filter

approvals

array of ApprovalRecord

RunSummary

runId

string

startedAt

string (date-time)

outcome

drafted, approved, sent, refused, failed

citationCount

integer

uncited

boolean

An uncited draft cannot be promoted to a send

trigger

RunTrigger

RunTrigger

The schedule tick a governed run was started from. Absent on a run that was started without a trigger, which reads as absent rather than as a fabricated tick.

kind *

schedule

caller *

string

The verified client principal that started the run, never a value the run's own request supplied.

taskId *

string

scheduledAt *

string (date-time)

ScheduleTriggerRequest

A schedule tick a registered machine client starts a run from.

kind *

schedule

taskId *

string

scheduledAt *

string (date-time)

The tick's instant, timezone-aware

key *

string

The tick's canonical key, recomputed from the task id and the scheduled instant; a value that does not match is refused.

ScheduleEventRequest

A tick a scheduler observed but did not fire, reported so it is recorded rather than silent.

kind *

skipped

reason *

missed

taskId *

string

scheduledAt *

string (date-time)

The tick's instant, timezone-aware

key *

string

The tick's canonical key, recomputed from the task id and the scheduled instant; a value that does not match is refused.

DeniedRequest

at

string (date-time)

caller

string

kind

retrieval_denied, egress_blocked, credential_expired, scope_refused

reason

string

ReviewBundle

One period of one agent's evidence, as an auditor reads it. Built only from TimelineEntry and release identifiers: there is no field here a document body or a raw prompt could occupy. Plain JSON, readable without Necto tooling.

bundleVersion *

string

The bundle format, so a reader can tell versions apart

exportId *

string

agentId *

string

exporter *

string

The verified subject that asked for the export

exportedAt *

string (date-time)

periodFrom *

string (date-time)

periodTo *

string (date-time)

retentionCutoff

string (date-time)

Nothing before this is guaranteed to still exist

complete *

boolean

False when the period begins before the retention cutoff

incompleteReason

string

entryCount

integer

releases

array of object

runs

array of object

TimelineEntry

Immutable. Identifiers and decisions only: no document text, no raw prompts, no credential values.

at *

string (date-time)

kind *

sandbox_created, sandbox_resumed, sandbox_timeout, sandbox_killed, sandbox_start_denied, sandbox_start_failed, sandbox_exec_failed, run_finished, sandbox_stop_failed, scope_checked, retrieval_decided, candidate_dropped, credential_injected, draft_produced, approval_decided, send_attempted, action_replay_refused, export_created, containment_triggered, workload_stopped, authority_revoked, service_restored, identity_asserted, authority_resolved, authority_granted, authority_withdrawn, release_decided, standing_approval_revoked, ttl_exception_granted, credential_withdrawn, api_request, caller_first_seen, promotion_requested, promotion_decided, promotion_executed, schedule_fired, schedule_skipped, schedule_refused

sandbox_resumed is reserved and never emitted: the runtime interface has no resume operation. Do not branch on it.

evidenceClass

semantic, infrastructure

The entry's own class: semantic for a kind the four behavioural dimensions read, infrastructure for every other kind the record names. A word, never a number or a score. An entry presented as semantic agent evidence is checked before it is presented, and a refusal names the kind.

issuer

string

Which identity provider vouched for caller. A sub is unique only within its issuer, and a later dispute needs to know which provider asserted it. Under federation this is the origin, not the console, so a federated login's entry names the provider that actually asserted it.

customerId *

string

The third part of the authority key. The same human may exist under more than one customer.

agentId

string

The agent an entry is about, where that is not implied by the run it belongs to. A containment event is the case that needs it: stopping an agent is not part of a run, and "which agent was contained" is the first question an incident review asks.

workloadId

string

The workload a lifecycle entry is about. An identifier the substrate issued, never a substrate handle.

profileHash

string

releaseVersion

string

grantId

string

The standing approval a revocation entry ends. An identifier of the grant, never its channel, message or approver.

artifactDigest

string

The prebuilt artifact the workload started from: an E2B template build id (a UUID), built outside the platform process, never a template name, alias or tag. The released identifier the sandbox was actually created from, so "what ran" is answerable from the record rather than from the release store's current state.

owner

string

Who owns the agent, carried from the compiled metadata. Distinct from caller, which is whoever made the request an entry records.

caller

string

taskId

string

The scheduled task a schedule_fired, schedule_skipped or schedule_refused entry is about. It names the task whose tick did or did not run.

scheduledAt

string (date-time)

The tick's scheduled instant, timezone-aware. A tick is an instant, not a period.

key

string

The tick's canonical key, recomputed from the task id and the scheduled instant. A repeated key never starts a second run. Absent on a tick refused before it could have run: no key names a tick that has not happened.

purpose

string

The declared purpose the query ran under. A decision is not reconstructable without it.

environment

string

The environment the query ran in. Staging never reaches a production source; the record proves which one asked.

application

string

The application the record is about, from the deployment record's (customer, application, environment) triple. An identifier, never the application's source, configuration or content.

component

string

The plan component within the application the record is about. A component name, never the component's command, image or environment.

deploymentId

string

The deployment record the entry is about: the id a promotion approval records as its target head and the deployment store compares. An identifier, never the deployment's actor, plan or artifact.

connector

string

Which connector made the source decision. An identifier, never a credential or an endpoint.

documentId

string

documentVersion

string

location

string

decision

allow, deny

reason

string

Required on a deny. A silent drop is indistinguishable from a retrieval miss and destroys the audit trail. On a tick refused before it could have run it is future.

tokenId

string

Identifier only, never the token value

envelopeId

string

The action envelope an entry is about. An approval binds the envelope's hash, so a reviewer asking whether an action was executed, and executed once, has it in hand. The id is what joins send_attempted to action_replay_refused.

queryHash

string

Salted

citations

array of string

The citation set, as document@version#location identifier triples: the passages a step relied on, never the passages themselves.

upstreamIdentityPath

array of string

An identity_asserted or authority_resolved entry's whole upstream identity path, as issuer#subject#verification_basis identifier triples, at most two, origin first. verification_basis is one of id_token_verified, broker_verified_origin or broker_authenticated. issuer and caller above already name the first entry; this carries the rest of the chain. Absent for a non-federated login.

method

string

HTTP method of the request an api_request entry records. An identifier of the call, never the call itself.

pathTemplate

string

The matched route's path template, such as /agents/{agentId}/card, never the concrete path. Absent on an unmatched route, where only the concrete path exists.

routeName

string

The matched route's name. unmatched when no route matched: an unmatched route is a refusal, and its record has to say which path could not.

status

integer

The response status the request produced.

outcome

served, refused, failed

The refusal/fault taxonomy, on api_request entries: served is a 2xx; refused is Necto considering a request and saying no (the 4xxs); failed is Necto unable to answer (the 5xxs). Not decision's retrieval enum.

latencyBucket

under_100ms, 100ms_1s, 1s_10s, over_10s

Coarse response latency, an ordered bucket, not the raw duration.

exitCode

integer

The artifact entrypoint's own exit result, recorded unchanged. Present only on a run that ended: 0 ran, and the entrypoint's own non-zero code is the entrypoint's own result, not a platform refusal.

stdoutBytes

integer

The number of UTF-8 bytes the entrypoint wrote to stdout, never the output itself. Present only on a run that ended, so a silent refusal is visible without any output reaching the record.

stderrBytes

integer

The number of UTF-8 bytes the entrypoint wrote to stderr, never the output itself. Present only on a run that ended, so a silent refusal is visible without any output reaching the record.

RegimeKey

The release regime a baseline and an observation are keyed to: one agent, one compiled profile and one release. A release opens a new regime; a prior regime's baseline is kept for comparison and never scores the next one.

agentId *

string

profileHash *

string

releaseVersion *

string

BehaviourRange

A closed range. Both ends are included.

minimum *

number

maximum *

number

BehaviourRefusal

One refused attempt, carrying the rule that refused it. A refusal is an observation, never an absence: an attempt the platform refused is returned here rather than dropped from the comparison. Identifiers only, never content, passages, prompts or credentials.

identifier

string

The document, destination or tool identifier the attempt named, when the record names one.

rule *

string

The rule that refused the attempt, as the record states it.

BehaviourCollection

One document a run read, or was refused.

name *

string

result *

read, refused

rule

string

The rule that refused the read; absent when it was read.

BehaviourDestination

One destination a run contacted, or was refused.

name *

string

result *

sent, refused

attempts

integer

The number of attempts the run's own record carries with this name and result: the send attempts the platform allowed for a sent destination, and the attempts the named rule refused for a refused one.

rule

string

The rule that refused the send; absent when it was sent.

BehaviourComparison

One dimension's comparison verdict. neutral when the run's values are inside the regime's baseline; review when they are outside it or an attempt on the dimension was refused. Never a number.

verdict *

neutral, review

reason

string

Plain words for a review verdict; absent when neutral.

BehaviourComparisons

The comparison verdict for each of the four dimensions.

information *

BehaviourComparison

destinations *

BehaviourComparison

tools *

BehaviourComparison

volume *

BehaviourComparison

RegimeTransition

Where one regime's baseline ended and the next began, derived from the agent's own run records.

endedAt *

string (date-time)

ended *

RegimeKey

beganAt *

string (date-time)

began *

RegimeKey

BehaviourBaselineInformation

The documents a usual run reads, and how many it opens.

documents *

array of string

recordsPerRun

BehaviourRange

Absent while the regime has no observed run.

BehaviourBaselineDestinations

The destinations a usual run contacts.

destinations *

array of string

BehaviourBaselineTools

The tool order a usual run follows.

order *

array of string

BehaviourBaselineVolume

The records-per-run and run-seconds a usual run shows.

recordsPerRun

BehaviourRange

Absent while the regime has no observed run.

runSeconds

BehaviourRange

Absent while the regime has no observed run.

BehaviourBaseline

What is usual for one agent in one release regime. state is ready when the regime has enough observed history to compare against, and insufficient_volume when it does not: the state scores nothing, and no verdict is returned rather than a low one.

agentId *

string

regime

RegimeKey

Absent when no run names a regime yet.

state *

ready, insufficient_volume

reason

string

Why the state is insufficient_volume; absent when ready.

observedRuns *

integer

The number of the regime's finished runs this baseline summarises. The platform holds no separate review record, so this is an observation count and never a claim that a person reviewed each run.

minimumVolume

integer

The configured minimum the state is read against; absent when the deployment configures none, and then the state is insufficient_volume rather than ready.

information *

BehaviourBaselineInformation

destinations *

BehaviourBaselineDestinations

tools *

BehaviourBaselineTools

volume *

BehaviourBaselineVolume

transitions

array of RegimeTransition

BehaviourInformation

The documents one run read, or was refused.

collections *

array of BehaviourCollection

records

integer

How many records the run opened.

BehaviourDestinations

The destinations one run contacted, or was refused.

destinations *

array of BehaviourDestination

BehaviourTools

The tools one run used, in order, and those refused.

order *

array of string

refusals

array of BehaviourRefusal

BehaviourVolume

The records one run opened and the seconds it ran.

records *

integer

seconds

number

Absent when the run has no recorded end.

BehaviourObservation

One run's observed behaviour on the four dimensions, compared with the baseline of the regime that run belongs to, as it stood before the run started. Only that regime's runs that finished before this run started count. Refused attempts are observations carrying the rule that refused them, never dropped. state is insufficient_volume when the regime has too little observed history to compare against, and then comparison is absent: the run scores nothing rather than badly.

runId *

string

agentId *

string

regime

RegimeKey

The regime this run was compared against.

state *

ready, insufficient_volume

reason

string

Why the state is insufficient_volume; absent when ready.

observedRuns *

integer

The number of the regime's runs that finished before this run started, which the comparison baseline summarises. The platform holds no separate review record, so this is an observation count and never a claim that a person reviewed each run.

minimumVolume

integer

The configured minimum the state is read against; absent when the deployment configures none.

information *

BehaviourInformation

destinations *

BehaviourDestinations

tools *

BehaviourTools

volume *

BehaviourVolume

comparison

BehaviourComparisons

Absent while the state is insufficient_volume.

AuthorityCheck

tool *

string

allowed *

boolean

authority

read_only, draft_only, write_reversible, write_external

Present when allowed is true

reason

string

Required when allowed is false

TaskCompileResult

narrowed *

boolean

Always true: a 200 is returned only once every axis is confirmed a subset of the target agent's compiled artifacts. A response that would carry false is a 422 Problem instead.

agentId *

string

agentVersion

string

The agent's last approved release version, when one exists

data *

array of string

The task's own narrow.data, already confirmed a subset

tools *

array of string

The task's own narrow.tools, already confirmed a subset

authority *

read_only, draft_only, write_reversible, write_external

The task's own requested authority

droppedData *

array of string

The profile's data minus the task's narrow.data

droppedTools *

array of string

The profile's tools minus the task's narrow.tools

grantedAuthority *

read_only, draft_only, write_reversible, write_external

The profile's own authority ceiling

scheduled

object

Present only when the applied task carried a schedule. The recorded schedule carries its invocation beside the narrowing, so a scheduler can reconstruct the run without the task file.

TaskSummary

One recorded kind: Task apply that carried a schedule. The record carries the compiled invocation (input, deliver, authority, narrowed data/tools) and the tenant key, so a scheduler can reconstruct the run.

customerId *

string

The deployment's own tenant key, recorded with the task. Deployment-supplied, never taken from a request, claim or header.

taskId *

string

agentId *

string

schedule *

string

Five-field cron in UTC, validated by the standard-tier trigger validator at compile. A malformed schedule is refused by name, never recorded.

input *

string

The task's own input, kept for the scheduler

deliver *

string

The task's own deliver, kept for the scheduler

authority *

read_only, draft_only, write_reversible, write_external

The task's own requested authority

data *

array of string

The task's narrowed narrow.data

tools *

array of string

The task's narrowed narrow.tools

createdAt

string (date-time)

MutationRecord

One collaboration mutation, as the append-only journal recorded it: the actor, the organisation, the application, the object kind and id, the action and the resulting version. Every field is an identifier — never a comment body, prompt or payload. A clone lands as a plan_version, never as a kind of its own.

customerId *

string

The deployment's own tenant key, recorded with the mutation. Deployment-supplied, never taken from a request, claim or header. The read is already tenant-keyed; the key is carried so the record says what it is keyed by.

organisationId *

string

The first-class organisation the mutation belongs to, recorded beside the tenant key. Strictly inside the customer, never a second tenant axis; the record carries it so a caller can tell which organisation a mutation belongs to.

actor *

string

The mutation's assertion-resolved subject

application *

string

objectKind *

comment, plan_version, role_grant, membership, component

objectId *

string

action *

created, cloned, granted, revoked

resultingVersion *

string

at *

string (date-time)

HistoryEntry

One derived version-history entry: the anchor kind, the identifier its store knows it by, the time the store recorded and the actor where the store has one. at and actor are absent where the owning store has neither — a plan version carries no clock and no actor, a run record carries no actor. parent is a plan version's lineage by hash. Nothing here is invented to fill a gap.

anchor *

plan_version, deployment, release, run

identifier *

string

at

string (date-time)

actor

string

parent

string

WhoAmI

caller *

string

The stable subject identifier this caller resolved to. Under federation this is the origin entry's sub on the assertion, not the console's.

customer *

string

role *

string

approvalAuthority

boolean

Whether this caller may approve a release hash

FederationProvider

One record of the committed federation registry, rendered for the console server that reconciles its provider list against it. Identifiers and display fields only, never a secret: the upstream issuer, the record's Necto-side customer id, the named endpoint hosts and the allowed verification bases. No client credential, domain or endpoint path is in the record or the answer.

issuer *

string (uri)

The upstream identity provider's issuer identifier, as the record holds it.

customerId *

string

The Necto-side customer the record is for; every record this deployment answers carries the deployment's own.

jwksHost *

string

The named host serving the issuer's JWKS

discoveryHost

string

The named discovery endpoint host, when configured

tokenHost

string

The named token endpoint host, when configured

userinfoHost

string

The named user-info endpoint host, when configured

allowedVerificationBases *

array of string

The verification bases the record allows, e.g. id_token_verified; the console's own basis must be among them.

ObservedDestination

One refused destination, identifier-only. The destination's own identifiers and the platform's own instants, plus the bounded attempt counter; no payload, content or capture field exists. The tenant key, the run's governed-component identity and the run come from the deployment and the verified workload claims, never from a request body. The attempt counter is a bounded count, never a score. A repeat observation advances lastSeenAt and never moves observedAt; capReached marks the run's single cap-reached record, written once when a new destination arrives past the per-run cap.

destinationId *

string

The stable identifier for this observed destination; the decision record and the customer-plane routes name it.

customerId *

string

The deployment's own customer id

applicationId *

string

The run's governed-component identity -- the profile name the run route resolved -- never a body field

runId *

string

The run whose egress refused the destination

host *

string

The named host the run tried, normalized; never a wildcard, a CIDR, a scheme, a port or a path

port *

integer

protocol *

tcp, tls

observedAt *

string (date-time)

The platform's own instant at the first observation; a repeat counts and never moves it

lastSeenAt *

string (date-time)

The platform's own instant at the most recent observation; a repeat advances it

attempts *

integer

The bounded attempt count; a repeat observation coalesces into the row and increments it up to the platform's cap

capReached *

boolean

The run's one cap-reached record: true when a new destination arrived past the per-run cap, so the refusal list is bounded and the cap is recorded rather than sampled