Developer Documentation

Introduction

The NotarAI API is a REST API that accepts JSON bodies and returns JSON responses. All requests must be made over HTTPS. HTTP requests are rejected.

Responses use standard HTTP status codes. Successful responses return a JSON object with the resource data. Errors return a JSON object with an error string field and an optional code machine-readable identifier.

Storage retention policy

Uploaded and generated files are not retained forever. NotarAI applies automatic retention windows to control storage costs and keep account usage predictable.

Authentication

All API requests are authenticated with a Bearer token. Tokens are created in the Developer settings and take the form ntr_live_key_<keyId>_<secret>.

Include the token in every request using the Authorization header:

Authorization: Bearer ntr_live_key_a1b2c3d4e5f6_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes

Each API key is created with one or more scopes. Requests that require a scope your key does not have will be rejected with 403 Forbidden.

Quick Start

The typical workflow is: scan → sign → verify. Scan uploads a file and extracts AI metadata. Sign applies a C2PA manifest with a disclosure declaration. The sign wizard now includes an explicit Article 50 acknowledgment before the final submit action. Use sign-jobs and scan-jobs for large-volume async processing.

Standard Workflow (Start Here)

For most teams, the fastest path is the synchronous flow below. You can validate value end-to-end without job queues, polling, or webhooks.

API Reference

Scan files

Upload one or more files to extract AI-generated content metadata. Each file is stored in your vault and analysed separately. Optionally assign uploads directly to an existing collection or create a new collection in the same request. Required scope: scan.

Request — multipart/form-data

Response — 200 OK

{
  "collectionId": "7dbfa9dd-4c48-4e39-a44c-0fc3c2206f73",
  "createdCollection": true,
  "results": [
    {
      "fileName": "hero.jpg",
      "recordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "metadata": {
        "hasC2PA": false,
        "hasXMP": true,
        "aiModel": "dall-e-3"
      }
    },
    {
      "fileName": "video.mp4",
      "error": "Unsupported MIME type"
    }
  ]
}

{
  "results": [
    {
      "fileName": "image.png",
      "recordId": "f6da3344-0358-4db2-942a-16e9426d0e1f",
      "metadata": {
        "hasC2PA": true,
        "hasXMP": false,
        "aiModel": "dall-e-3",
        "rawFields": {
          "DigitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia"
        },
        "c2paManifest": {
          "active_manifest": "urn:c2pa:2af52d28-d242-4e13-b126-147720f765e7",
          "manifests": {
            "urn:c2pa:2af52d28-d242-4e13-b126-147720f765e7": {
              "title": "image.png",
              "instance_id": "xmp:iid:a8324672-a72d-4bb1-8b0f-78c51b921d6c",
              "claim_generator_info": [
                {
                  "name": "OpenAI Media Service API",
                  "specVersion": "2.2.0",
                  "org.contentauth.c2pa_rs": "0.79.2"
                }
              ],
              "assertions": [
                {
                  "label": "c2pa.actions.v2",
                  "data": {
                    "actions": [
                      {
                        "action": "c2pa.created",
                        "when": "2026-04-29T00:00:00Z",
                        "softwareAgent": {
                          "name": "gpt-image",
                          "version": "pre-2.0"
                        },
                        "digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia"
                      },
                      {
                        "action": "c2pa.converted",
                        "when": "2026-04-29T00:00:00Z"
                      }
                    ]
                  }
                },
                {
                  "label": "c2pa.certificate-status",
                  "data": {
                    "ocspVals": [
                      "MIIE1goBAKCCBM8wggTLBgkrBgEFBQcwAQEEggS8MIIEuD...<very long value omitted>..."
                    ]
                  }
                }
              ],
              "signature_info": {
                "alg": "Es256",
                "issuer": "OpenAI OpCo, LLC",
                "common_name": "OpenAI Media Service",
                "time": "2026-04-29T19:55:02.160659+00:00"
              },
              "claim_version": 2
            }
          },
          "validation_status": [
            {
              "code": "signingCredential.untrusted",
              "url": "self#jumbf=/c2pa/urn:c2pa:2af52d28-d242-4e13-b126-147720f765e7/c2pa.signature",
              "explanation": "signing certificate untrusted"
            }
          ],
          "validation_results": {
            "activeManifest": {
              "success": [
                {
                  "code": "claimSignature.validated",
                  "explanation": "claim signature valid"
                },
                {
                  "code": "assertion.dataHash.match",
                  "explanation": "data hash valid"
                }
              ],
              "informational": [
                {
                  "code": "timeStamp.untrusted",
                  "explanation": "timestamp cert untrusted: OpenAI TSA Leaf"
                }
              ],
              "failure": [
                {
                  "code": "signingCredential.untrusted",
                  "explanation": "signing certificate untrusted"
                }
              ]
            }
          },
          "validation_state": "Valid"
        }
      }
    }
  ]
}

Sign a file

Apply a C2PA manifest to one or more previously scanned files. The manifest embeds the AI disclosure declaration cryptographically. An Article 50 audit certificate PDF is also generated per asset. The signed result page shows whether the asset was processed with the node SDK or c2patool and whether the file format received an embedded C2PA manifest. Required scope: sign.

Pass a single UUID string for recordId to sign one asset, or pass an array of UUIDs (max 50) to sign multiple assets in parallel. The response shape mirrors the input — a single object for single, a results array for batch.

{
  "recordId": ["3fa85f64-5717-4562-b3fc-2c963f66afa6", "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"],
  "declaration": {
    "aiModel": "other",
    "customModel": "my-custom-model-v1",
    "modificationType": "generation",
    "modificationDescription": "Text-to-image generation with prompt and negative prompt tuning",
    "purpose": "advertising",
    "purposeContext": "Paid social campaign for product launch",
    "humanReview": true,
    "reviewerName": "Jane Doe",
    "organization": "Acme Studio"
  }
}

Response — batch (array recordId) — 200 OK

{
  "results": [
    {
      "recordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "complete",
      "signedAssetUrl": "https://...",
      "certificateUrl": "https://...",
      "urlExpiresInSeconds": 600
    },
    {
      "recordId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
      "status": "error",
      "error": "Asset not yet scanned"
    }
  ],
  "count": 2
}

The returned download URLs are short-lived and should be used immediately. If they expire, call the endpoint again with the same recordIdto receive fresh URLs. In batch mode, a failure on one asset does not abort the rest — check each result’s status field.

Get verification record

Retrieve the public verification record for a signed asset. This endpoint is publicly accessible but requires scope verify.read when called with your API key. The record is identical to what is shown at https://notarai.io/verify/:id.

Path parameter

Response — 200 OK

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fileName": "campaign-hero.jpg",
  "mimeType": "image/jpeg",
  "fileHash": "sha256:e3b0c44298fc1c149afb...",
  "status": "complete",
  "declaration": {
    "aiModel": "dall-e-3",
    "purpose": "advertising",
    "modificationType": "generation",
    "humanReview": false
  },
  "createdAt": "2026-05-03T12:34:56.000Z",
  "completedAt": "2026-05-03T12:35:03.000Z",
  "verifyUrl": "https://notarai.io/verify/3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Sign Jobs (Async)

Sign jobs asynchronously apply declarations and signatures to many assets at once. This is the background processing API for high-volume signing.

Create a sign job

Asynchronously sign a set of assets. Supply either an assetIds array or a collectionId (not both).

Request body

curl -X POST https://notarai.io/api/v1/sign-jobs \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "declaration": {
      "signerName": "Acme Corp",
      "signerEmail": "publisher@acme.com",
      "article50": true
    }
  }'

{
  "job": {
    "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "status": "queued",
    "totalAssets": 250,
    "completedAssets": 0,
    "failedAssets": 0,
    "collectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdAt": "2026-05-07T10:00:00Z",
    "startedAt": null,
    "completedAt": null,
    "expiresAt": "2026-05-14T10:00:00Z",
    "error": null
  }
}

List sign jobs

Returns a paginated list of your batch jobs, newest first.

Query parameters

Get a sign job

Returns a single job. Append ?items=true to include per-asset statuses in the items array.

{
  "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "status": "completed",
  "totalAssets": 250,
  "completedAssets": 248,
  "failedAssets": 2,
  "collectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdAt": "2026-05-07T10:00:00Z",
  "startedAt": "2026-05-07T10:00:01Z",
  "completedAt": "2026-05-07T10:03:14Z",
  "expiresAt": "2026-05-14T10:00:00Z",
  "error": null
}

Scan Jobs (Async)

Scan jobs let you upload multiple files at once and scan them asynchronously in the background. Each file is stored and processed independently — results appear as individual scan records once the job completes.

Create a scan job

Upload one or more files as multipart/form-data. Each file is stored, queued, and scanned asynchronously. The response returns immediately with a job ID you can poll or receive via webhook.

Request fields (multipart/form-data)

Query parameters

curl -X POST "https://notarai.io/api/v1/scan-jobs?collectionId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@photo1.jpg" \
  -F "file=@photo2.png"

{
  "job": {
    "id": "7d94f943-d1c2-4f1c-8e31-4c3074df5412",
    "status": "queued",
    "totalAssets": 2,
    "completedAssets": 0,
    "failedAssets": 0,
    "collectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdAt": "2026-05-07T10:00:00Z",
    "startedAt": null,
    "completedAt": null,
    "expiresAt": "2026-05-14T10:00:00Z",
    "error": null
  }
}

List scan jobs

Returns a paginated list of your scan jobs, newest first.

Get a scan job

Returns a single scan job. Append ?items=true to include per-asset scan statuses in the items array.

Rate Limits

There are no hourly rate limits. The primary constraint is your plan's monthly quota. Exceeding it returns 429 Too Many Requests. A Retry-After header is included when the response is rate-limited.

Monthly quotas

Error Codes

All errors return a JSON body with an error human-readable message and a code machine-readable string.

{
  "error": "API key does not have the required scope: sign",
  "code": "INSUFFICIENT_SCOPE"
}

Changelog