> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Feedback

> Report a data issue, bug, or feature request through the API

## Overview

Submit structured feedback about the Signa API or its data. This is the programmatic reporting channel: use it to flag an inaccurate record, report a server error you hit, or request a capability. It is designed for both humans and AI agents acting on your behalf.

Every submission is stored in your organization, posted to the Signa team for triage, and readable back so you can watch it move through its status lifecycle. Feedback is never billed (`0` units) and runs on generous rate limits, so reporting a problem never costs you anything.

Any valid API key may submit feedback for its organization; no special scope is required. An `Idempotency-Key` header is required (the standard mutating-request rule), so a retried submission never creates a duplicate.

## Feedback types

The required `type` discriminator routes and categorizes the report:

| `type`            | Use it for                                                                                                                                                                   |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data_issue`      | A record disagrees with the official registry (wrong owner name, stale status, missing field). Pair with `resource_id`, `field`, and `expected_value` to make it actionable. |
| `bug`             | The API behaved incorrectly (an unexpected error, a wrong response shape). Attach `request_id` so we see exactly what you saw.                                               |
| `feature_request` | A capability you want that does not exist yet.                                                                                                                               |
| `other`           | Anything that does not fit the above. A `message` alone is always valid.                                                                                                     |

## Request Body

<ParamField body="type" type="string" required>
  One of `data_issue`, `bug`, `feature_request`, `other`.
</ParamField>

<ParamField body="message" type="string" required>
  Free-form report body (1 to 5000 characters).
</ParamField>

<ParamField body="resource_id" type="string">
  Public ID of any referenced entity (`tm_...`, `own_...`, `att_...`, `firm_...`, `prc_...`). At submit time the server snapshots the record's current state into `context.resource`.
</ParamField>

<ParamField body="request_id" type="string">
  The `request_id` of the API request where you observed the problem (`req_...`, or a client-supplied `x-request-id`; up to 64 URL-safe characters). At submit time the server snapshots the matching request log into `context.request`.
</ParamField>

<ParamField body="field" type="string">
  For data issues: which field is wrong (for example `owner.name`). Up to 255 characters.
</ParamField>

<ParamField body="expected_value" type="string">
  For data issues: what the value should be. Up to 5000 characters.
</ParamField>

<ParamField body="metadata" type="object">
  Optional string-to-string map for your own tags (max 50 keys).
</ParamField>

## Submit-time enrichment

When you reference a `request_id` or a `resource_id`, Signa captures an investigation snapshot into the read-only `context` object at submit time. This matters because request logs are dropped after roughly four months while feedback lives indefinitely, and because a record can be overwritten by a later sync. The snapshot preserves what you saw.

Enrichment never rejects a submission. An unknown, foreign, or non-existent reference is recorded as `null` or `found: false` rather than returning an error.

**`context.request`** is present when you sent `request_id`:

* An object `{ route, method, status_code, error_type, error_detail, duration_ms, occurred_at }` when the request is found within your organization.
* `null` when the request id is unknown or belongs to another organization (no cross-org leakage).

**`context.resource`** is present when you sent `resource_id`:

* `{ found: true, resource_type, office, jurisdiction, version, status_primary, source_updated_at, updated_at }` when the record exists (with `null` where a given entity type lacks a field).
* `{ found: false, resource_type }` when the record does not exist.

A `context` key is simply absent when the corresponding reference was not provided or the snapshot could not be captured.

## Response

Returns the created feedback object with HTTP `201`.

<ResponseField name="id" type="string">The feedback identifier (`fbk_...`).</ResponseField>
<ResponseField name="object" type="string">Always `feedback`.</ResponseField>
<ResponseField name="api_key_id" type="string | null">Public ID (`key_...`) of the API key that filed this report, for per-key attribution within your org. `null` if unattributed.</ResponseField>
<ResponseField name="type" type="string">The submitted type (`data_issue`, `bug`, `feature_request`, `other`).</ResponseField>
<ResponseField name="status" type="string">Lifecycle status: `open` on creation, then `acknowledged` or `resolved`.</ResponseField>
<ResponseField name="message" type="string">The report body you submitted.</ResponseField>
<ResponseField name="resource_id" type="string | null">The referenced entity's public ID, echoed back, or `null`.</ResponseField>
<ResponseField name="request_ref" type="string | null">The `request_id` you referenced, echoed verbatim. Named `request_ref` because the envelope reserves the top-level `request_id` for this API call.</ResponseField>
<ResponseField name="field" type="string | null">The field you flagged, or `null`.</ResponseField>
<ResponseField name="expected_value" type="string | null">The value you expected, or `null`.</ResponseField>
<ResponseField name="context" type="object">Server-built investigation snapshots (`context.request`, `context.resource`). Read-only, never client-supplied. See [Submit-time enrichment](#submit-time-enrichment).</ResponseField>
<ResponseField name="resolution_note" type="string | null">The Signa team's note when the report is resolved, or `null`.</ResponseField>
<ResponseField name="metadata" type="object">Your string-to-string metadata map.</ResponseField>
<ResponseField name="created_at" type="string">ISO timestamp when the report was submitted.</ResponseField>
<ResponseField name="updated_at" type="string">ISO timestamp of the last status change.</ResponseField>
<ResponseField name="resolved_at" type="string | null">ISO timestamp when the report was resolved, or `null`.</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "id": "fbk_550e8400-e29b-41d4-a716-446655440000",
    "object": "feedback",
    "api_key_id": "key_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "type": "data_issue",
    "status": "open",
    "message": "The registered owner is out of date; this mark was assigned last year.",
    "resource_id": "tm_9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "request_ref": "req_01kpjabcdefghijkmnpqrstvwx",
    "field": "owner.name",
    "expected_value": "Acme Holdings LLC",
    "context": {
      "request": {
        "route": "/v1/trademarks/{id}",
        "method": "GET",
        "status_code": 200,
        "error_type": null,
        "error_detail": null,
        "duration_ms": 12,
        "occurred_at": "2026-07-10T12:34:56.000Z"
      },
      "resource": {
        "found": true,
        "resource_type": "trademark",
        "office": "uspto",
        "jurisdiction": "US",
        "version": 3,
        "status_primary": "active",
        "source_updated_at": "2026-07-01T00:00:00.000Z",
        "updated_at": "2026-07-02T08:00:00.000Z"
      }
    },
    "resolution_note": null,
    "metadata": {},
    "created_at": "2026-07-10T12:40:00.000Z",
    "updated_at": "2026-07-10T12:40:00.000Z",
    "resolved_at": null,
    "request_id": "req_cW8oQ3rT"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.signa.so/v1/feedback" \
    -H "Authorization: Bearer sig_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: data-issue-tm-9f8e7d6c-001" \
    -d '{
      "type": "data_issue",
      "message": "The registered owner is out of date; this mark was assigned last year.",
      "resource_id": "tm_9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      "field": "owner.name",
      "expected_value": "Acme Holdings LLC"
    }'
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

  const feedback = await signa.feedback.create({
    type: "data_issue",
    message: "The registered owner is out of date; this mark was assigned last year.",
    resource_id: "tm_9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    field: "owner.name",
    expected_value: "Acme Holdings LLC",
  });

  console.log(feedback.id, feedback.status); // fbk_...  open
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                                                                               |
| ------ | ------------------ | ----------------------------------------------------------------------------------------- |
| 400    | `validation_error` | Missing `type`/`message`, message out of range, or a malformed `resource_id`/`request_id` |
| 401    | `unauthorized`     | Missing or invalid API key                                                                |
| 409    | `conflict`         | `Idempotency-Key` reused with a different body                                            |
| 429    | `rate_limited`     | Too many requests                                                                         |

## Related Endpoints

* [List Feedback](/api-reference/administration/list-feedback), review everything your org has reported
* [Retrieve Feedback](/api-reference/administration/get-feedback), check the status of one report
* [Get Request Log](/api-reference/administration/get-log), look up the `request_id` you want to attach