OpenOrigins API

Environments

Stage

Base URL

dev

https://dev-api.openorigins.com

prod

https://api.openorigins.com

All examples below use prod.

Authentication

Generate an API key in Dashboard → Settings → API Keys (to be made) (or contact OpenOrigins support if the dashboard access isn’t enabled yet).

Headers

x-api-key: <API-KEY-VALUE>

Endpoints

GET /v1/users

List users of your organization

Authorization: API Key

Query params

Name

Default

Description

limit

Items per page

page

Page number

Paginated endpoints echo page and limit in the response for convenience.

Response

"page": and "limit": duplicate query param

response 200

{
    "total": <TOTAL_NUMBER_OF_USERS_IN_THE_ORGANIZATION>,
    "page": <PAGE>,
    "limit": <LIMIT>,
    "items": [
        {
	<USER_MODEL>
        }
    ]
}

Example

request

curl -H "x-api-key: $API_KEY" \
     "https://api.openorigins.com/v1/users?limit=20&page=2"

raw HTTP

GET /v1/users?limit=20&page=2 HTTP/1.1
Host: api.openorigins.com
x-api-key: <YOUR_API_KEY>

response 200

{
  "total": 42,
  "page": 2,
  "limit": 20,
  "items": [
    <USER_MODEL>
  ]
}

GET /v1/media

List media items of your organization

Authorization: API Key

Query params:

Name

Default

Description

limit

Items per page

page

Page number

"page": and "limit": duplicate query param

response 200

{
    "total": <TOTAL_NUMBER_OF_MEDIA_ITEMS_IN_THE_ORGANIZATION>,
    "page": <PAGE>,
    "limit": <LIMIT>,
    "items": [
        {
<MEDIA_ITEM_MODEL>
        }
    ]
}

Example

request

curl -H "x-api-key: $API_KEY" \
     "https://api.openorigins.com/v1/media?limit=10&page=1"

Raw HTTP

GET /v1/media?limit=10&page=1 HTTP/1.1
Host: api.openorigins.com
x-api-key: <YOUR_API_KEY>

response 200

{
  "total": 158,
  "page": 1,
  "limit": 10,
  "items": [
    <MEDIA_ITEM_MODEL>
  ]
}

GET /v1/media/{mediaId}

Get a single media item by its ID

Authorization: API Key

Route params: {mediaId} - media Id

Example

request

curl -H "x-api-key: $API_KEY" \
     "https://api.openorigins.com/v1/media/e24f4592-6a13-4763-9d88-f2793a52345f"

Raw HTTP

GET /v1/media/e24f4592-6a13-4763-9d88-f2793a52345f HTTP/1.1
Host: api.openorigins.com
x-api-key: <YOUR_API_KEY>

response 200

{
    "id": "e24f4592-6a13-4763-9d88-f2793a52345f",
    "hash": "102766d39213c0c9142079ee42ecb4db1d97699bf3e3fdf85a14b79e0619b39eb4f87a771fb82ecf71478cbbd0dc500a2c7770ea812d2fe0bf2d8c916fb78d22",
    "name": null,
    "size": 12345,
    "thumbnail": "https://dev-cdn.openorigins.com/thumbnails/pgmoiudduwuzrsxnglqctfpyqqqheqro.jpg",
    "status": 3,
    "createdOn": "2025-05-03T12:39:30.212576+00:00",
    "createdBy": {
        "id": "16628214-c0c1-70c7-ab35-1a8293cbbf49",
        "firstname": "Jane",
        "lastname": "Doe",
        "createdOn": "2025-04-01T07:53:52.330698+00:00",
        "profilePicture": "https://dev-cdn.openorigins.com/profile/vprpvrnuafsfptvsattrkdqgbxilnfry.png",
        "organization": {
            "id": "7be5ad62-6319-4bdc-9fe2-4e8768a75205",
            "name": "OpenOrigins",
            "websiteUrl": "openorigins.com",
            "createdOn": "2025-04-01T07:08:12.209896+00:00"
        }
    },
    "metadata": "{}",
    "transaction": {
        "transactionId": "0x7d81d72fc4a060b5f827b7d6aba43f7036a34fa0b84f1551ddbd4a9c95491d8c",
        "blockId": "0x7354fc7d04d0ff07dbe58fa284c79f0837062fa3c0c09dfc853160c169ebdfd5",
        "blockNumber": 35294316,
        "networkValidators": 1,
        "anchoredTime": 1746275975,
        "createdOn": "2025-05-03T12:39:36.229179+00:00"
    }
}

Name

Value

Meaning

status

Created

status

Accepted for anchoring

status

Anchored

status

Failed to anchor

POST /v1/media/anchor

Anchor media details

Authorization: API Key

Form Data:

id - media ID (optional)
name - media name (optional)
hash - media SHA3-512 hash
size - media size in bytes
metadata - any string of metadata (serialized json / xml, etc)

request

curl -X POST "https://api.openorigins.com/v1/media/anchor" \
     -H "x-api-key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "hash": "102766d39213c0c9142079ee42ecb4db1d97699bf3e3fdf8...",
           "size": 12345,
           "name": "scan_1944.tif",
           "metadata": "{}"
         }'

raw HTTP

POST /v1/media/anchor HTTP/1.1
Host: api.openorigins.com
Content-Type: application/json
x-api-key: <YOUR_API_KEY>

{
  "hash": "102766d39213c0c9142079ee42ecb4db1d97699bf3e3fdf8...",
  "size": 12345,
  "name": "scan_1944.tif",
  "metadata": "{}"
}

response 200

{
  "hash": "102766d39213c0c9…",
  "size": 12345,
  "name": "scan_1944.tif",
  "metadata": "{}"
}

response 201

{
  "id": "e24f4592-6a13-4763-9d88-f2793a52345f"
}

Response repeats the one sent by you or returns a new one if none were provided in the request.

GET /v1/public/media/{mediaHash}

Public lookup (no key). Get media details from its hash

Authorization: None

Route params:

mediaHash - media SHA3-512 hash

Example

GET /v1/public/media/102766d39213c0c9…

Returns the same object schema as Retrieve one media item or 404 if unknown

response 200

{
    "hash": "102766d39213c0c9142079ee42ecb4db1d97699bf3e3fdf85a14b79e0619b39eb4f87a771fb82ecf71478cbbd0dc500a2c7770ea812d2fe0bf2d8c916fb78d22",
    "name": null,
    "size": 12345,
    "thumbnail": "https://dev-cdn.openorigins.com/thumbnails/pgmoiudduwuzrsxnglqctfpyqqqheqro.jpg",
    "createdOn": "2025-05-03T12:39:30.212576+00:00",
    "metadata": "{}",
    "transaction": {
        "transactionId": "0x7d81d72fc4a060b5f827b7d6aba43f7036a34fa0b84f1551ddbd4a9c95491d8c",
        "blockId": "0x7354fc7d04d0ff07dbe58fa284c79f0837062fa3c0c09dfc853160c169ebdfd5",
        "blockNumber": 35294316,
        "networkValidators": 1,
        "anchoredTime": 1746275975,
        "createdOn": "2025-05-03T12:39:36.229179+00:00"
    }
}

Error model

All error responses are JSON:

response 400

{
  "code": "INVALID_HASH",
  "message": "Hash must be 128‑char lowercase hexadecimal.",
  "details": null
}

HTTP

Code

When it happens

400

INVALID_HASH

Hash not 128-char hex

401

UNAUTHENTICATED

Missing / bad key

403

RATE_LIMIT

Too many requests

404

NOT_FOUND

Unknown ID or hash

409

DUPLICATE

Hash already anchored

500

SERVER_ERROR

Unexpected exception

PreviousUsing This Reference NextEnd-to-End Anchoring Workflow

Last updated 5 months ago