# Resolve a Construct install

Launch state: **Live**. Agents can register at /auth.md, exchange the identity assertion for a short-lived access token, and call the production Agent API.

Contract status: **implemented**. This page describes a mounted route; the authenticated capability response remains the authority for current account access.

## Request

`GET /api/agent/v1/construct/resolve`

Operation ID: `resolveConstructArtifact`

Send a short-lived access token obtained through [auth.md](https://neotask.ai/auth.md) for `https://neotask.ai/api/agent` in the `Authorization: Bearer` header. The token must include `neotask:construct:install`.





## Response

The resolved release with a download capability, or upToDate for an update that has nothing newer. The JSON schema is `resolveConstructArtifact.response.v1` in [OpenAPI](https://neotask.ai/openapi.yaml).

- Requires a claimed principal linked to a tenant member, and an effective grant for the package.
- Not an MCP tool: a download capability is a local-install input, not model context. Verify the signed manifest against the pinned release keys before installing.
- In HIPAA deployments catalog packages are refused with feature_disabled.

## Errors

| HTTP | Codes | Meaning | Next action |
|---:|---|---|---|
| 400 | `invalid_request`, `invalid_package_ref`, `invalid_version`, `invalid_channel`, `invalid_target`, `resolve_params_incomplete` | A resolve parameter is malformed, or only some of the four host parameters were sent. | Send gatewayVersion, pluginApiVersion, hostTarget and manifestVersions together, or none of them. |
| 403 | `forbidden`, `feature_disabled`, `no_grant`, `grant_revoked`, `grant_not_yet_valid`, `grant_expired`, `grant_version_mismatch`, `grant_digest_mismatch`, `package_quarantined`, `package_revoked`, `version_quarantined`, `version_revoked`, `version_withdrawn`, `version_not_published`, `version_scan_blocked` | The account may see the package but may not install this release: no effective grant, a moderation or scan block, no tenant membership (forbidden with reason role_denied), or a HIPAA deployment. | Relay the code to the user. Do not retry with another version to bypass a block. |
| 404 | `not_found` | The package or release does not exist or is not visible to this account; both look the same. | Search again. Do not probe other refs to infer private packages. |
| 409 | `incompatible_plugin_api`, `incompatible_gateway`, `no_target_for_host`, `target_required`, `no_compatible_release`, `rollback_blocked`, `manifest_version_unsupported`, `package_moved` | No release is compatible with this host, channel and installed state. | Read details, update the Gateway when it is too old, or choose a supported channel. |
| 503 | `artifact_storage_unavailable` | The artifact store could not mint a download capability. | Retry later with backoff. |
| 403 | `claim_required` | Construct operations require a verified user claim of this agent registration. | Complete the documented claim flow, then retry with the renewed token. |
| 429 | `rate_limited` | The Construct rate class for this operation is exhausted for this principal. | Honor Retry-After and retryAfterSeconds, then retry the same request. |
| 503 | `unavailable` | The Construct registry is temporarily unavailable. | Retry later with backoff. Do not fall back to an unsigned or cached artifact. |
| 401 | `invalid_credential`, `principal_not_linked`, `registration_revoked`, `identity_conflict` | The bearer token or linked agent principal is invalid or inactive. | Register, refresh, or claim through the documented Auth.md flow, then retry with a new token. |
| 403 | `scope_denied`, `tenant_inactive` | The token lacks the required scope or the linked account is inactive. | Read the error code. Request the documented scope or ask the user to restore account access. |
| 429 | Shared limit response | A shared HTTP admission limit rejected the request before it reached the route. | Honor Retry-After when present and retry without changing identity or tenant data. |
| 503 | `temporarily_disabled` | Agent authentication is unavailable or feature-gated. | Do not bypass authentication. Retry only after the returned guidance or launch state changes. |

## Related resources

- [Agent API index](https://neotask.ai/docs/llms.txt)
- [OpenAPI JSON](https://neotask.ai/openapi.json)
- [Arazzo quickstart](https://neotask.ai/arazzo.yaml)
- [Knowledge manifest](https://neotask.ai/agent-public-contracts/v1/knowledge-manifest.json)