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

# API Reference

> Selected implemented TexasVerified route handlers, authentication boundaries, and request shapes.

# API Reference

TexasVerified implements Next.js route handlers under `apps/web/src/app/api`. Most are same-origin application routes authenticated by the Auth0 session cookie.

Authentication for native mobile routes uses Auth0 Bearer tokens. The web Worker verifies the JWT's RS256 signature, issuer, audience, and lifetime before resolving the database-backed principal.

Set `APP_ORIGIN` to the origin of the deployment you are testing. No production app origin is asserted by this documentation.

```bash theme={null}
: "${APP_ORIGIN:?set APP_ORIGIN to the deployment origin}"
curl --fail-with-body "$APP_ORIGIN/api/health"
```

## Selected route surface

| Method | Path | Access | Purpose |
| - | - | - | - |
| `GET` | `/api/health` | Public; admins get extra diagnostics | Health and version check |
| `GET` | `/api/verify/[certificateNumber]` | Public | Look up public member data for a certificate number |
| `POST` | `/api/onboarding/lookup` | Authenticated user | Look up Comptroller locations by Taxpayer ID; a lookup failure does not block manual entry |
| `POST` | `/api/onboarding` | Authenticated user without org | Create retailer organization and first location |
| `POST` | `/api/uploads` | Retailer owner/staff or admin | Store multipart file in Drive; queue OCR |
| `GET` | `/api/team` | Retailer owner or admin | List organization members |
| `POST` | `/api/team` | Retailer owner | Invite or add a staff member |
| `PATCH` | `/api/organization` | Retailer owner or admin | Update legal name and DBA |
| `POST` | `/api/locations` | Retailer owner or admin | Add a location with permit identifiers |
| `PATCH` | `/api/locations/[locationId]` | Retailer owner or admin | Update location and permit identifiers |
| `POST` | `/api/auditor/access-requests` | Auditor | Create auditor access request |
| `PATCH` | `/api/auditor/access-requests/[id]` | Retailer owner or admin | Approve, decline, or revoke access request |
| `GET` | `/api/tasks` | Grant participant | List compliance tasks by grant |
| `POST` | `/api/tasks` | Auditor or admin | Create compliance task |
| `PATCH` | `/api/tasks/[taskId]` | Grant participant | Auditor edits, completes, or reopens the task; a retailer may only set `status` to `submitted_for_review` from `open` or `changes_requested` |
| `POST` | `/api/tasks/[taskId]/comments` | Grant participant | Add comment or reply |
| `POST` | `/api/tasks/[taskId]/documents` | Grant participant | Attach document to task |
| `GET` | `/api/compliance/checklist` | Authenticated | Checklist data for mobile app |
| `GET` | `/api/certificates/[certificateNumber]/pdf` | Bearer auth | Download certificate PDF |
| `GET` | `/api/locations` | Authenticated | Caller's locations with permit records |
| `POST` | `/api/ocr/jobs` | Owner or admin | Manual OCR reprocess |
| `POST` | `/api/drive-items/[id]/reclassify` | Authenticated | Manual Drive section correction |
| `POST` | `/api/marketing/orders` | Owner or admin | Create marketing fulfillment order |
| `POST` | `/api/public-page` | Owner or admin | Update public member page |
| `GET` | `/api/org-events/token` | Authenticated | Mint push-event subscription |
| `PATCH` | `/api/supplier/purchase-inquiries/[id]` | Owner or admin | Confirm or decline inquiry |
| `POST` / `DELETE` | `/api/wallet/design` | Owner or admin | Save or remove Wallet pass design |
| `GET` | `/api/files/[...key]` | Authenticated | Authorized file retrieval from R2 |
| `GET` | `/api/compliance/resources/mirror/[uuid]` | Authenticated | Private compliance convenience copy |
| `POST` | `/api/stripe/webhook` | Stripe public | Stripe webhook receiver |
| `GET` | `/m/[certificateNumber]` | Public | Public certificate verification page |
| `GET` | `/m/[certificateNumber]/badge.svg` | Public | Embeddable SVG badge |

## Public certificate lookup

The public lookup trims the certificate number, rejects empty or over-64-character values, and returns 404 when no public member record exists.

```bash theme={null}
curl -i "$APP_ORIGIN/api/verify/TXV-CERTIFICATE-NUMBER"
```

## Upload a Drive file

The upload handler expects multipart fields named `locationId`, `section`, and `file`. The `section` must be one of `notice`, `form`, `coa`, `invoice`, `receipt`, `compliance_image`, `certificate`, `permit`, `agreement`, or `other`.

The request requires a valid Auth0 session.

```bash theme={null}
curl --fail-with-body -X POST -b session-cookies.txt \
  -F locationId=00000000-0000-0000-0000-000000000000 \
  -F section=coa -F file=@coa.pdf \
  "$APP_ORIGIN/api/uploads"
```

The handler rejects empty files, unsupported MIME types, files above 50 MB, exceeded storage quotas, and locations the caller does not manage. A successful write returns HTTP 201 with the OCR-queued state.

## Auditor routes

Auditor routes are served from `app/(audit)` and use Auth0 Bearer token or session authentication:

* `GET /audit/locations` — auditor's requested locations ledger
* `GET /audit/locations/[grantId]` — single-location compliance review
* `GET /audit/tasks` — auditor task list
* `GET /audit/tasks/[taskId]` — auditor single-task detail

## Worker surface

Supporting workers handle internal processing that is not part of the public integration surface. These include inbound document intake, background OCR and notification processing, scheduled authority-data sync, and realtime change signaling. They are reached through private service-to-service paths. The one exception is inbound intake: external providers deliver to the intake endpoints listed on the [Webhooks](https://docs.pcnaid.com/nodes/web-apps/texasverified/developer/webhooks/index.md) page, which are public receivers rather than integration APIs.

This is deliberately not an exhaustive route catalog. Administrative review, webhook, evidence, and internal reevaluation handlers exist but are not documented here as external integration surfaces.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.