# Report 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

`POST /api/agent/v1/construct/installs`

Operation ID: `reportConstructInstall`

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`.

Send an `Idempotency-Key` header with 8-200 characters. Reuse it only for an identical retry. For 24 hours, an identical retry returns the outcome recorded for the first request, with the same status and body, instead of running the operation again; a recorded failure is returned as that same failure. A readiness refusal returned before the operation started (for example `setup_required` with `runner_not_enrolled`, or `temporarily_disabled` with `run_execution_disabled`, `runner_offline` or `cloud_gateway_not_connected`) is not recorded, so the identical retry runs once the runner or gateway is ready.

The JSON request body uses `reportConstructInstall.request.v1` in OpenAPI.

## Response

The report was accepted; deduplicated is true when the same installation already reported this event today. The JSON schema is `reportConstructInstall.response.v1` in [OpenAPI](https://neotask.ai/openapi.yaml).

- Requires a claimed principal linked to a tenant member. Counts are per installation and day; no content from the installation is stored.
- The CLI sends nothing when the install-report opt-out is set.

## Errors

| HTTP | Codes | Meaning | Next action |
|---:|---|---|---|
| 400 | `invalid_request`, `invalid_idempotency_key` | The request body or Idempotency-Key is malformed. | Correct the documented input. Reuse an idempotency key only for the identical mutation. |
| 403 | `forbidden` | The linked member holds no tenant role (reason role_denied). | Ask an account owner to restore the membership. |
| 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 | `idempotency_conflict`, `idempotency_in_progress` | The idempotency key belongs to another request or its first request is still running. | Do not change the request under the same key. Retry later or use a new key for new work. |
| 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)