> ## Documentation Index > Fetch the complete documentation index at: https://docs.myrqen.cc/llms.txt > Use this file to discover all available pages before exploring further. # Create a cloud report shell > Creates the report shell and returns a live URL immediately. The sync unit is **reserved** here and **spent** at finalize, so an object-storage failure in the upload leg never burns one of the day's cloud reports. Idempotent on `localReportId`: a retried request reuses the same reservation and never charges twice, and returns 200 instead of 201. Source is never accepted here. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/reports openapi: 3.1.0 info: title: Myrqen API version: 1.0.0 description: >- The JSON API served by `apps/web` under `/api/v1`. Derived from the route handlers in `apps/web/app/api/v1` and the shared types in `packages/contracts`. This reference documents the surface a developer and the Myrqen CLI actually use. Platform-administration and billing endpoints exist in the application but are operator-only and are deliberately not published here. The hosted service at `https://api.myrqen.cc` is not deployed yet. Run your own deployment and use its origin. license: name: Myrqen Source-Available Licence 1.0 url: https://github.com/stijnswapped/Myrqen/blob/main/LICENSE servers: - url: http://localhost:3000 description: >- A deployment you run yourself. Use this while the hosted service is unavailable. - url: https://api.myrqen.cc description: >- The hosted API. This is the CLI's shipped default, but the hosted service is NOT deployed yet, so requests to it do not resolve today. security: [] tags: - name: Health description: >- Liveness and readiness probes. Unauthenticated, and answered on any hostname. - name: Authentication description: Browser sessions. Password plus recovery codes; no email is ever sent. - name: Device linking description: Binding a machine's CLI to an account, via browser approval. - name: Workspaces and projects description: Where a scanned repository belongs. - name: Sync and quota description: Creating, feeding, and finalizing a cloud report. - name: Reports description: Reading and exporting a synced report. - name: Sharing description: Share links and the server-side projections they resolve to. - name: Analytics description: Allowlisted product-event ingest. - name: Updates description: The signed release manifest. paths: /api/v1/reports: post: tags: - Sync and quota summary: Create a cloud report shell description: >- Creates the report shell and returns a live URL immediately. The sync unit is **reserved** here and **spent** at finalize, so an object-storage failure in the upload leg never burns one of the day's cloud reports. Idempotent on `localReportId`: a retried request reuses the same reservation and never charges twice, and returns 200 instead of 201. Source is never accepted here. operationId: createReport requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateReportRequest' example: workspaceId: wsp_… projectId: prj_… localReportId: rpt_9f0c… effortRequested: auto effortResolved: high projectName: vuln-shop agent: name: claude-code version: 2.1.0 model: claude-opus-5 host: osFamily: darwin arch: arm64 cliVersion: 0.1.0 responses: '200': description: The shell already existed for this `localReportId`. content: application/json: schema: $ref: '#/components/schemas/CreateReportResponse' '201': description: Created. content: application/json: schema: $ref: '#/components/schemas/CreateReportResponse' example: reportId: rep_… reportUrl: https://myrqen.cc/app/reports/rep_… state: live expiresAt: '2026-09-10T12:00:00.000Z' quota: eligible: true daily: used: 3 limit: 5 resetsAt: '2026-08-21T06:00:00.000Z' weekly: used: 8 limit: 15 resetsAt: '2026-08-24T06:00:00.000Z' retentionDays: 21 plan: free '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '403': $ref: '#/components/responses/Forbidden' '429': description: >- `SYNC_DAILY_LIMIT_REACHED` or `SYNC_WEEKLY_LIMIT_REACHED`. `details` carries both windows. The scan still runs locally. content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - deviceToken: [] components: schemas: CreateReportRequest: type: object required: - workspaceId - projectId - localReportId - effortRequested - agent - projectName properties: workspaceId: type: string projectId: type: string localReportId: type: string description: >- The CLI's local report id. Also the idempotency key for the quota reservation. effortRequested: $ref: '#/components/schemas/EffortRequested' effortResolved: $ref: '#/components/schemas/EffortResolved' agent: $ref: '#/components/schemas/AgentMetadata' host: $ref: '#/components/schemas/HostEnvironment' projectName: type: string maxLength: 200 CreateReportResponse: type: object required: - reportId - reportUrl - state - expiresAt - quota properties: reportId: type: string reportUrl: type: string format: uri state: type: string const: live expiresAt: type: string format: date-time quota: $ref: '#/components/schemas/SyncQuota' ApiError: type: object required: - error properties: error: type: object required: - code - message - requestId properties: code: $ref: '#/components/schemas/ApiErrorCode' message: type: string description: Human-readable. May change; branch on `code`. requestId: type: string description: A fresh UUID per response, for correlating with server logs. details: type: object additionalProperties: true example: error: code: SYNC_WEEKLY_LIMIT_REACHED message: Cloud report limit reached. This scan stays local. requestId: 8f14e45f-ceea-467a-9f8b-2b6b2b6a1f2c details: weekly: used: 15 limit: 15 resetsAt: '2026-08-24T06:00:00.000Z' EffortRequested: type: string enum: - low - high - xhigh - ultra - auto EffortResolved: type: string enum: - low - high - xhigh - ultra AgentMetadata: type: object required: - name properties: name: type: string version: type: string model: type: string HostEnvironment: type: object required: - osFamily - arch properties: osFamily: type: string arch: type: string runtimeVersion: type: string cliVersion: type: string isolatedRuntimeAvailable: type: boolean SyncQuota: type: object required: - eligible - daily - weekly - retentionDays - plan description: >- Quota windows are UTC-anchored: the day runs 06:00 UTC to 06:00 UTC, the week runs Monday 06:00 UTC to Monday 06:00 UTC. properties: eligible: type: boolean daily: $ref: '#/components/schemas/SyncQuotaWindow' weekly: $ref: '#/components/schemas/SyncQuotaWindow' blockedBy: type: string enum: - daily - weekly - both retentionDays: type: integer plan: $ref: '#/components/schemas/PlanId' ApiErrorCode: type: string enum: - BAD_REQUEST - VALIDATION_FAILED - UNAUTHENTICATED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL - DEVICE_LINK_EXPIRED - DEVICE_LINK_ALREADY_CONSUMED - DEVICE_LINK_NOT_APPROVED - DEVICE_REVOKED - SYNC_DAILY_LIMIT_REACHED - SYNC_WEEKLY_LIMIT_REACHED - REPORT_EXPIRED - REPORT_SCHEMA_UNSUPPORTED - UNSAFE_PAYLOAD_REJECTED - SHARE_PASSWORD_REQUIRED - SHARE_NOT_AVAILABLE - CLIENT_VERSION_REVOKED - CLIENT_VERSION_TOO_OLD - SUPPORT_GRANT_REQUIRED SyncQuotaWindow: type: object required: - used - limit - resetsAt properties: used: type: integer limit: type: integer resetsAt: type: string format: date-time PlanId: type: string enum: - free - pro - team - enterprise responses: BadRequest: description: >- `BAD_REQUEST`. Also returned with HTTP 413 when a body exceeds the endpoint's byte limit. content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthenticated: description: >- `UNAUTHENTICATED` — no credential, a malformed credential, or one that did not match. `DEVICE_REVOKED` also uses 401. content: application/json: schema: $ref: '#/components/schemas/ApiError' Forbidden: description: '`FORBIDDEN` — authenticated, but not permitted.' content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: deviceToken: type: http scheme: bearer description: >- The CLI's device credential, obtained once from the device-link exchange and stored in the OS keystore. Sent as `Authorization: Bearer myrq_dev_…`. The server never trusts a CLI-supplied user id — identity comes from the credential row. ````