Rights Check API

Getting started

1. Get a key. During the pilot, imageRelease creates keys for you. Each key belongs to one organisation.
2. Keep it on your server. Treat it like a password. Never put it in a web page, a mobile app or a public repository. If it leaks, ask us to revoke it.
3. Send it with every request in the Authorization header.

Base address:

Always call https://imagerelease.uk directly. Other hostnames redirect, and a redirect drops the uploaded image.

Check your set-up:

Checking an image

Send one image as multipart/form-data in a field called image. JPEG, PNG, WebP and TIFF are accepted, up to 20 MB. The type is read from the file's contents, not its name.

curl -H "Authorization: Bearer irk_live_your-key" \
     -F "image=@photo.jpg" \
     https://imagerelease.uk/api/ext/v1/checks

An image your organisation holds a licence for:

{
  "checkedUtc": "2026-10-08T15:35:05Z",
  "matched": true,
  "canUse": "allowed",
  "summary": "Your organisation holds an accepted licence for this image.",
  "c2pa": { "present": false, "valid": null, "issuer": null },
  "matches": [
    {
      "level": "exact",
      "distance": 0,
      "trust": "unverified",
      "disputeCount": 0,
      "registrations": [
        {
          "type": "media_licence",
          "status": "active",
          "relationship": "licensee",
          "visibility": "party",
          "canUse": "allowed",
          "reasons": [ "Your organisation accepted this licence." ],
          "displayRef": "ML-20261008-2C2D84",
          "terms": {
            "validFrom": "2026-10-08T15:07:46Z",
            "validUntil": null,
            "territory": "European Economic Area (EEA) and UK",
            "exclusivity": "non-exclusive",
            "usageTypes": [ "In all media, without limitation" ],
            "assignmentAllowed": false,
            "ai": { "training": "prohibited", "generative": "prohibited", "dataMining": "prohibited" }
          }
        }
      ]
    }
  ]
}

The image is compared with the ledger and then discarded. The one exception: when it matches a registered image only weakly, a small copy (512 pixels across) may be kept so that our team can confirm the match by eye. It isn't linked to your organisation and is deleted once reviewed, and in any case within 90 days.

Reading the answer

Start with canUse, which is the answer for your organisation, and summary, a sentence you can show to people as it is. The detail is in matches.

Owner and licensee

Each registration says how it relates to your organisation (relationship):

• owner: your organisation registered it, for example an image rights request it raised.
• licensee: a licence for it was accepted from the email address of one of your organisation's members on imageRelease. A licence accepted from an address that isn't a member of your organisation won't show as yours.
• none: neither.

You see the full terms and reference only for your own registrations (visibility: party). For other organisations' registrations you see the type, status and date (visibility: public), and, where the image was registered as available under an open licence, the licence, any credit and the source link. You don't see their terms, references or uploaders, and a check never says who holds the rights: a registration records what was declared, not who owns the image.

Matches

Images are matched by their visual fingerprint, so edited copies (cropped, resized or recompressed) still match. level is exact, high or medium; distance runs from 0 (identical) to 15. c2pa reports Content Credentials found in the file you sent.

Reporting a wrong match

If a match isn't the same image, tell us within 90 days, quoting the result's checkId and the match's place in matches (counting from 0; leave it out when there was only one). Reports go to our team to improve matching: the matched image's owner isn't told and nothing changes in the ledger. Reporting the same match again returns the first report. If the image you checked is online, send its https link as imageUrl so our team can compare the two: we keep only the link, and fetch the image when we review the report.

curl -H "Authorization: Bearer irk_live_your-key" -H "Content-Type: application/json" \
     -d '{"match": 0, "reason": "Our photo is a workshop; the match is a stage show.", "imageUrl": "https://example.com/media/workshop.jpg"}' \
     https://imagerelease.uk/api/ext/v1/checks/{checkId}/report

201 Created
{ "reportId": "…", "checkId": "…", "match": 0, "status": "received" }

Registering images

For sites that publish images, such as through the imageRelease Umbraco package. Keys need the registrations:write scope. Send the image with a metadata field saying where it came from and what its uploader declared; it is registered against your organisation, not stored or altered, and counts against your plan's registration allowance.

curl -H "Authorization: Bearer irk_live_your-key"      -F "image=@photo.jpg"      -F 'metadata={"sourceRef":"media-1234","site":"example.com","channel":"event-upload","declaration":"owner","uploaderRef":"member:5678"}'      https://imagerelease.uk/api/ext/v1/registrations

• declaration: owner or permission make the image allowed for your organisation; not_declared (the default), third_party_feed and historic record it without claiming rights (no_rights_declared).
• Open licences: declaration open_licence with licence (unsplash, pexels, cc0, cc-by-4.0, cc-by-sa-4.0, public-domain, or other with licenceName: the licence's name, up to 100 characters, no email addresses, and only sent with other), the author in credit where the licence asks for it, and sourceUrl (https) where the image and licence can be seen. Your organisation then gets allowed; anyone else checking the image gets open_licence with those details.
• uploaderRef: only a pseudonymous reference (member:{id}, user:{id} or system). Names and email addresses are refused.
• Who said what (feature assertion-fields in /me): each declaration is an assertion (owner is owns; permission and open_licence are licensed; the rest are uses), worked out for you. basis says who stands behind it: declared_by_uploader for an uploader's own answer, passed on as given, or declared_by_recorder for your organisation's statement. A default you apply when the uploader didn't answer is yours: send it as declared_by_recorder, and on channels where members upload, make the default not_declared. Without basis, an answer from a member: declarant counts as the uploader's. Use declarantRef when someone other than the uploader answered (an editor correcting it). Use not_sure when the uploader said they don't know, and keep not_declared for no answer.
• Free text, as given and never checked, up to 200 characters, no email addresses: rightsHolder for an owned or licensed image (from whom it is licensed, or with onBehalfOf: true for whom you hold it, e.g. a PR company for a venue); attribution for an image used without known rights (where it came from); credit stays what to print with the image. Also ownershipBasis (created or assigned_in_writing, with owner), aiGenerated and usedFrom.
• The answer (201) gives the ledger reference, and says whether the image was already in the ledger (isNewImage, existingRegistrations); check it with /checks to see whose.
• When you check a registered image later, your registrations show a provenance block with what you sent, plus assertion, basis, the use period (usedFromUtc, usedUntilUtc) and any replaced or replacing registration. Reasons say who made the statement: an uploader's answer reads as theirs and "not verified". Other organisations never see these; for an uploader's open-licence answer they read "An uploader declared this image available ...", without your site's name.
• To change a declaration (feature supersede), register the same image again with supersedesRegistrationId set to the old registration: it becomes superseded in the same step, kept as history rather than withdrawn, and stops counting towards your allowance. It must be your organisation's active registration of the same file (404 supersede_not_found, 409 supersede_refused otherwise; nothing is registered then). A different file is a new registration: end the old one's use instead. replacesRegistrationId, which revokes the old one, still works but is deprecated.
• When your site stops showing an image, for example a past event's picture is swapped out or the image is deleted, record that its use ended (feature use-ended): POST https://imagerelease.uk/api/ext/v1/registrations/{registrationId}/use-ended, optionally with {"usedUntil": "2026-11-03T00:00:00Z"} (now when left out). The registration stays, as the record that the use happened. It is set once: the same time again is fine (changed: false), a different one is 409 use_already_ended. If the image is shown again, register it again.
• Revoke a registration only if it was made by mistake: DELETE https://imagerelease.uk/api/ext/v1/registrations/{registrationId}. The ledger keeps it, marked revoked.
• When you erase a member or user from your site, remove their reference from your registrations (feature declarant-erase): POST https://imagerelease.uk/api/ext/v1/declarants/erase with {"declarantRef": "member:5678"}, optionally "site" to limit it to one site and "dryRun": true to count first. Wherever that reference was sent, it becomes [erased]; the registrations stay. The answer gives registrationsRedacted. Safe to repeat.

Limits

• Requests per minute, per key. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.
• Images per month (calendar month, UTC), per key. Checks carry X-Quota-Limit and X-Quota-Remaining. Only successful checks count.
• Failed keys: after repeated requests with a missing or invalid key from one address, further failures are refused for a while. Valid keys are not affected.

Over a limit, you get 429 with a Retry-After header in seconds. Wait that long before trying again.

Errors

Errors are RFC 9457 problem details (application/problem+json). Branch on code; title and detail are for people and may change. Quote traceId when asking for help.

{
  "type": "about:blank",
  "title": "Monthly quota used",
  "status": 429,
  "detail": "This key can check 1000 images a month. The count resets on 1 November 2026 (UTC).",
  "code": "quota_exceeded",
  "traceId": "0HNP5ALQ04EMU:00000001"
}

Your key and usage

• GET https://imagerelease.uk/api/ext/v1/me: the key's name, organisation, environment, scopes and limits. organisation gives the organisation's name, slug and verifyUrl, a link to its verify page on imageRelease. Add ?imageUrl= and an image's public https address (URL-encoded) to fill in the page's link field. The link only fills in the field: a member of the organisation must log in and press Verify. features lists newer features this server accepts; metadata fields it doesn't know are ignored rather than refused, so send a newer field only when its feature is listed.
• GET https://imagerelease.uk/api/ext/v1/usage: images checked and registered and requests made this month, what is left, when it resets, and a day-by-day breakdown.
• GET https://imagerelease.uk/api/ext/v1/ping: whether the API is reachable. No key needed.

Privacy

• Images you send are compared and discarded. The only exception is a weak match: we may keep a 512 pixel copy for our team to check by eye, not linked to your organisation, deleted once reviewed and in any case within 90 days.
• We log each call: the key, time, address, endpoint, outcome and a short summary of the result. Logs are deleted after 180 days.
• Results never include personal details of the people in images or the parties to an agreement, or any fees.
• When you register images, you are the controller of that data and we act for you (our Data Processing Addendum). Send an uploader only as a reference such as member:1234; the API refuses names and email addresses.
• rightsHolder, attribution and credit can name someone who isn't your user, such as a photographer. Send them only as your uploader gave them, keep them short, and never include contact details. Only your organisation (and our administrators) see them; an open licence's credit is also shown to anyone who checks the image, because the licence requires it.
• A changed answer is kept as history (superseded), and an ended use stays on record, as the evidence a dispute needs. When you erase a member or user from your site, erase their reference here too (POST https://imagerelease.uk/api/ext/v1/declarants/erase).

Telling the people who upload to your site

If people upload images to your website and you register them, say so in your privacy notice. Suggested wording, to adapt:

And a shorter line for the upload form itself:

Reference

The full contract is the OpenAPI document: https://imagerelease.uk/api/ext/v1/openapi.json. Import it into Postman, Insomnia or a code generator.

Within v1, fields are only ever added, never renamed, removed or changed in meaning, so ignore fields you don't recognise. Anything that would break that promise gets a new version.