# Public documents API

The Public Documents API lets browser code upload and manage a submission's documents without exposing your private API key. It provides the [Documents](https://docs.niva.co/doc-599891.md) operations using a public API key and a submission token. Requests are accepted from any origin through Cross-Origin Resource Sharing (CORS).

## Authentication

You need both credentials:

- **Public API key**: send it in the `apiKey` header. Create a public key (`ntpub_…`) in the Niva dashboard under **Settings › API Keys**. A private key is rejected with `401`.
- **Submission token**: replace `{submission_token}` in the path with the submission's `token`, returned by [Create new submission](https://docs.niva.co/api-8802390.md) or [Get submission](https://docs.niva.co/api-8802391.md). Retrieve it on your server with a private key and pass it only to the applicant who should access that submission. It expires 24 hours after issue; call Get submission for a fresh token.

For example, list the submission's documents:

```bash
curl 'https://api.niva.co/v1/public/submissions/YOUR_SUBMISSION_TOKEN/documents' \
  --header 'apiKey: YOUR_PUBLIC_API_KEY'
```

Replace both placeholders with your credentials.

## Endpoints

1. [Upload document (public)](https://docs.niva.co/api-25710910.md)
2. [List documents (public)](https://docs.niva.co/api-31119284.md)
3. [Get document (public)](https://docs.niva.co/api-25710936.md)
4. [Download document file (public)](https://docs.niva.co/api-45802058.md)
5. [Rerun validations (public)](https://docs.niva.co/api-45802059.md)
6. [Delete document (public)](https://docs.niva.co/api-25710938.md)

## Authentication errors

- `401` with `{"errors": ["401 Unauthorized"]}`: the `apiKey` header is missing, invalid, or not a public key.
- `401` with `{"errors": ["Invalid token."]}`: the submission token is malformed or expired.
- `404` with `{"errors": ["Record not found."]}`: the submission belongs to another account, or the document is not available in this submission.

For a ready-made upload interface, see [Document upload widget](https://docs.niva.co/doc-822376.md).