# Reports

Data corrections the account has reported. A report is how a consumer tells us a specification is wrong. It is reviewed by a person and never applied automatically; nothing here writes to the catalog. Session-scoped (`/v1/me/*`).

Source: https://docs.gunspec.io/en/sdk/reports

## client.reports.create()

`POST /v1/me/reports`

Auth: API key required  
Tier: Explorer+

Report an incorrect or missing value.

### Request body (application/json)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `firearmId` | string | yes | Slug of the firearm this row belongs to. |
| `section` | string | yes | Which part of the record the report is about. |
| `issueType` | string | yes | What kind of problem: `incorrect`, `missing`, `outdated`. |
| `description` | string | yes | Prose summary of the record, where one has been written. |
| `suggestedValue` | string | no | What the reporter believes the value should be. |
| `references` | string[] | no | Pages the reporter cited in support. |

```json
{
  "firearmId": "glock-g17-gen5",
  "section": "specs",
  "issueType": "incorrect",
  "description": "The barrel length is listed in inches, not millimetres.",
  "suggestedValue": "114",
  "references": [
    "https://example.com/spec-sheet"
  ]
}
```

### Response 201 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | DataReport | A community-submitted data correction against a firearm. |
| `data.id` | string | Opaque report id. |
| `data.firearmId` | string | Slug of the firearm this row belongs to. |
| `data.section` | string | Which part of the record the report is about. |
| `data.issueType` | ReportIssueType | What a data report says is wrong. |
| `data.description` | string | Prose summary of the record, where one has been written. |
| `data.suggestedValue` | string \| null | What the reporter believes the value should be. |
| `data.references` | string[] | Pages the reporter cited in support. |
| `data.status` | ReportStatus | Lifecycle of a data report. |
| `data.createdAt` | string | When the record was first added, `YYYY-MM-DD HH:MM:SS` in UTC. |
| `data.reviewedAt` | string \| null | When staff reviewed it, or null while it is pending. |

```json
{
  "success": true,
  "data": {
    "id": "rep_01H8",
    "firearmId": "glock-g17-gen5",
    "section": "specifications",
    "issueType": "incorrect",
    "description": "string",
    "suggestedValue": "114",
    "references": [
      "https://www.glock.com/en/products/g17"
    ],
    "status": "pending",
    "createdAt": "2026-08-23T02:00:00.000Z",
    "reviewedAt": null
  }
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 413 | `PAYLOAD_TOO_LARGE` | Request body too large |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Example

```bash
curl --request POST \
  --url 'https://api.gunspec.io/v1/me/reports' \
  --header 'X-API-Key: your_key' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firearmId": "glock-g17-gen5",
  "section": "specs",
  "issueType": "incorrect",
  "description": "The barrel length is listed in inches, not millimetres.",
  "suggestedValue": "114",
  "references": [
    "https://example.com/spec-sheet"
  ]
}
'
```

## client.reports.list()

`GET /v1/me/reports`

Auth: API key required  
Tier: Explorer+

The reports this account has filed, newest first, with their review state.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | no | Page number, from 1 to 10,000 |
| `per_page` | integer | no | Items per page (max 100) |

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | DataReport[] | A community-submitted data correction against a firearm. |
| `data[].id` | string | Opaque report id. |
| `data[].firearmId` | string | Slug of the firearm this row belongs to. |
| `data[].section` | string | Which part of the record the report is about. |
| `data[].issueType` | ReportIssueType | What a data report says is wrong. |
| `data[].description` | string | Prose summary of the record, where one has been written. |
| `data[].suggestedValue` | string \| null | What the reporter believes the value should be. |
| `data[].references` | string[] | Pages the reporter cited in support. |
| `data[].status` | ReportStatus | Lifecycle of a data report. |
| `data[].createdAt` | string | When the record was first added, `YYYY-MM-DD HH:MM:SS` in UTC. |
| `data[].reviewedAt` | string \| null | When staff reviewed it, or null while it is pending. |
| `pagination.page` | number | Current page number |
| `pagination.per_page` | number | Items per page |
| `pagination.total` | number | Total matching records (Builder and above) |

```json
{
  "success": true,
  "data": [
    {
      "id": "rep_01H8",
      "firearmId": "glock-g17-gen5",
      "section": "specifications",
      "issueType": "incorrect",
      "description": "string",
      "suggestedValue": "114",
      "references": [
        "https://www.glock.com/en/products/g17"
      ],
      "status": "pending",
      "createdAt": "2026-08-23T02:00:00.000Z",
      "reviewedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "per_page": 20,
    "total": 42,
    "totalPages": 3
  }
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Example

```bash
curl --request GET \
  --url 'https://api.gunspec.io/v1/me/reports' \
  --header 'X-API-Key: your_key'
```