REST API¶

All endpoints live under the base path /api/v1. The OpenAPI 3.0 document at iscc_web/static/docs/openapi.yaml is the source of truth for the API; every running instance serves interactive API documentation (Stoplight Elements) at /docs and the raw spec at /docs/openapi.yaml. Examples below target a local instance at http://localhost:8000 — the public demo instance is https://web.iscc.io.

Conventions¶

See Configuration for all ISCC_WEB_* and ISCC_SDK_* options.

Endpoint overview¶

ISCC¶

POST /iscc¶

Upload a media file and generate its ISCC. Returns ISCC metadata including the composite ISCC-CODE, individual ISCC-UNITs, technical metadata, and a thumbnail where applicable.

Request body: the raw file bytes (application/octet-stream or the file's actual media type).

Unsupported media types do not fail by default: with ISCC_SDK_FALLBACK=true (the default) they produce a wide 2-unit ISCC-SUM (Data + Instance) instead of 422.

curl -X POST "http://localhost:8000/api/v1/iscc?semantic=false&granular=true" \
  -H "X-Upload-Filename: $(printf 'test-image.jpg' | base64)" \
  -H "Content-Type: image/jpeg" \
  --data-binary @test-image.jpg

$filename = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("test-image.jpg"))
curl.exe -X POST "http://localhost:8000/api/v1/iscc?semantic=false&granular=true" `
  -H "X-Upload-Filename: $filename" `
  -H "Content-Type: image/jpeg" `
  --data-binary "@test-image.jpg"

Response (201, thumbnail truncated):

{
  "@context": "http://purl.org/iscc/context/0.8.0.jsonld",
  "@type": "ImageObject",
  "$schema": "http://purl.org/iscc/schema/0.8.0.json",
  "iscc": "ISCC:KECXNDSZVTTX2LDQYNBTBHR4T2HGOYBAGBNWZ767PKO3JQGZ42GFEAY",
  "media_id": "061kcmrj55fi8",
  "content": "http://localhost:8000/api/v1/media/061kcmrj55fi8",
  "name": "test image",
  "mode": "image",
  "filename": "test-image.jpg",
  "filesize": 53256,
  "mediatype": "image/jpeg",
  "width": 200,
  "height": 133,
  "thumbnail": "data:image/webp;base64,UklGRtIFAABXRUJQVlA4IMYFAADwIQCdASqAAFUAPxF0...",
  "generator": "iscc-sdk - v0.9.3",
  "metahash": "1e20304ab0c98a760be580dfa20716f2912d7ae30ec82b5f48b01dcf8f008d42568d",
  "datahash": "1e209db4c0d9e68c5203dc8c2fefe52fa5d54671be3a3253e06888cace7c60e5a743",
  "units": [
    "ISCC:AADXNDSZVTTX2LDQWWLJUWUK3DGIQV27EFWEUI2AEXNONCRDWUSE2OY",
    "ISCC:EED4GQZQTY6J5DTHQ2DWCPDZHQOM6QZQTY6J5DTFZ2DWCPDZHQOMXDI",
    "ISCC:GADWAIBQLNWP7X32J3INMAMDUJ4QMN67BBQKVTVZIWHXQ7QJIKHYTBY",
    "ISCC:IADZ3NGA3HTIYUQD3SGC737FF6S5KRTRXY5DEU7ANCEMVTT4MDS2OQY"
  ]
}

For text uploads with granular features enabled, the response additionally carries a features array of feature sets:

GET /iscc/{media_id}¶

Return the stored ISCC result for a previous POST /iscc upload. The stored result omits the volatile media_id and content fields.

curl http://localhost:8000/api/v1/iscc/061knt35ejv6o

Media¶

POST /media¶

Upload a file without ISCC processing (e.g. as preparation for metadata extraction).

Request body: the raw file bytes.

curl -X POST http://localhost:8000/api/v1/media \
  -H "X-Upload-Filename: $(printf 'test-image.jpg' | base64)" \
  -H "Content-Type: image/jpeg" \
  --data-binary @test-image.jpg

Response (201):

{
  "content": "http://localhost:8000/api/v1/media/061knt35ejv6o",
  "media_id": "061knt35ejv6o"
}

GET /media/{media_id}¶

Download an uploaded file. The response streams the original bytes with the Content-Type recorded at upload time and a Content-Disposition attachment filename.

curl -OJ http://localhost:8000/api/v1/media/061knt35ejv6o

DELETE /media/{media_id}¶

Delete an uploaded file and all stored results for it.

curl -X DELETE http://localhost:8000/api/v1/media/061knt35ejv6o

Metadata¶

GET /metadata/{media_id}¶

Extract metadata embedded in an uploaded media file. Returns only fields that are present: name, description, meta, identifier, creator, license, acquire, credit, rights.

curl http://localhost:8000/api/v1/metadata/061knt35ejv6o

Response (200):

{
  "name": "Concentrated Cat PNG",
  "creator": "Another Cat Lover"
}

POST /metadata/{media_id}¶

Embed metadata into a media file and reprocess its ISCC. The original file is not modified — a copy is created under a new media_id; the response content field links to the new file, which clients should offer for download.

Request body (application/json) — all fields optional:

curl -X POST http://localhost:8000/api/v1/metadata/061knt35ejv6o \
  -H "Content-Type: application/json" \
  -d '{"name": "The Never Ending Story", "creator": "Joanne K. Rowling"}'

The 201 response has the same shape as POST /iscc, with the new media_id/content and the submitted metadata merged in (e.g. "iscc": "ISCC:KECTN76LTY522ZPCYNBTBHR4T2HGO6RDNMJX4P6UMT5X2NVXB7F2FGA", "name": "The Never Ending Story", "creator": "Another Cat Lover, Joanne K. Rowling").

Explain¶

GET /explain/{iscc}¶

Decompose an ISCC and return alternative representations of the code and each of its units. Accepts canonical codes with or without the ISCC: prefix. This endpoint requires no upload and works on any valid ISCC.

curl http://localhost:8000/api/v1/explain/ISCC:KMDMRJYGHHVRCZ5TM6U4G6D4MXA6LAXC4ZRPOKFU7JBEQXR2BJOS6NA

Response (200, units abbreviated):

{
  "iscc": "ISCC:KMDMRJYGHHVRCZ5TM6U4G6D4MXA6LAXC4ZRPOKFU7JBEQXR2BJOS6NA",
  "readable": "ISCC-VIDEO-V0-MSDI-c8a70639eb1167b367a9c3787c65c1e582e2e662f728b4fa42485e3a0a5d2f34",
  "multiformat": "uzAFTBsinBjnrEWezZ6nDeHxlweWC4uZi9yi0-kJIXjoKXS80",
  "decomposed": "AAA4RJYGHHVRCZ5T-CMAWPKODPB6GLQPF-GAAYFYXGML3SRNH2-IAAUESC6HIFF2LZU",
  "units": [
    {
      "iscc_unit": "ISCC:AAA4RJYGHHVRCZ5T",
      "readable": "META-NONE-V0-64-c8a70639eb1167b3",
      "hash_hex": "c8a70639eb1167b3",
      "hash_uint": "14458531974522955699",
      "hash_bits": "1100100010100111000001100011100111101011000100010110011110110011"
    }
  ]
}

Simprint¶

POST /simprint¶

Generate granular simprints from plain text for similarity search. The output format is compatible with iscc-search and the granular features of POST /iscc. Simprint algorithms are experimental and may change before their v1.0 release.

Request body (application/json):

curl -X POST http://localhost:8000/api/v1/simprint \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello World! This is a short text for simprint generation."}'

Response (200):

{
  "CONTENT_TEXT_V0": [
    "SCXX_obwF2sK-xsnk9p1hhsH1fvrzwyZZBhhsVxMLTM"
  ],
  "SEMANTIC_TEXT_V0": [
    "emhK25dQAqnkcdcMuworif5t5GzDy8A3zmlDCEdAyWk"
  ]
}