Credential Evidence

Evidence is the work behind a credential: a project link, a report or an assessor’s note. It shows on the public credential page and in the Open Badges downloads. See Credential evidence for how it works in the Studio.

Method	URL	Does
`GET`	`/v1/credential/{document_id}/evidence`	Lists the evidence
`POST`	`/v1/credential/{document_id}/evidence`	Adds one item
`DELETE`	`/v1/credential/{document_id}/evidence/{evidence_id}`	Deletes one item

You can also send evidence when you issue: see the evidence field of Issue Credential. View Credential returns what the credential page shows.

Before you start

All URLs are on https://api.thehyperstack.com. Send your API key: Authorization: Bearer YOUR_API_KEY. Create a key in the Studio under Settings → Developers.
document_id is the credential’s key. evidence_id is the id of an item, from the list.
Adding needs credential evidence on your plan (Premium or Enterprise). Listing and deleting work on every plan, so evidence you added before a downgrade stays yours to manage.
Items you add with the API are your organization’s items, the same as items your team adds in the Studio.

Item fields

Every endpoint returns items in this shape:

string

The item’s ID. Use it to delete the item.

string

link, file or text.

string

The item’s title.

string

The text of a text item, or the description of a link or a file. Empty when there is none.

string

The link of a link item. Empty for the other kinds.

string

The link’s site name without www., such as github.com. Empty for the other kinds.

string

The address that opens the item: the link, or the file’s address on the credential page (https://hyperstack.id/credential/{document_id}/evidence/{id}). Empty for a text item. The file address checks who may open the file, then sends them to it. It does not change.

string

The name of the uploaded file. Empty for the other kinds.

string

application/pdf, image/png, image/jpeg or image/webp. Empty for the other kinds.

integer

The file’s size in bytes. 0 for the other kinds.

string

issuer for your items, recipient for items the recipient added.

boolean

true when your team hid a recipient’s item from the credential page.

string

Where the item was added: studio, sheet, api, mcp, wallet or page.

string | null

When the item was hidden (ISO 8601, UTC). null when it is not hidden.

boolean

true when the recipient deleted the item after your team hid it. Its title, link, text and file are gone, and it still uses one of the recipient’s 5 places. It can’t be shown again.

string | null

When the recipient deleted it. null otherwise.

string

When the item was added (ISO 8601, UTC).

string

When the item last changed (ISO 8601, UTC).

List evidence

GET https://api.thehyperstack.com/v1/credential/{document_id}/evidence

Returns every item of the credential: your items first, then the recipient’s, each in the order they were added. Hidden and removed items are in the list too.

curl "https://api.thehyperstack.com/v1/credential/6f1c2a8e-3b4d-4e5f-9a7b-1c2d3e4f5a6b/evidence" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 Success

{
  "success": true,
  "items": [
    {
      "id": "k3T9vQx2LmP8sR4w",
      "kind": "link",
      "title": "Capstone project repo",
      "narrative": "The app's code, with a README that explains how to run it.",
      "url": "https://github.com/janedoe/stockroom",
      "host": "github.com",
      "href": "https://github.com/janedoe/stockroom",
      "file_name": "",
      "file_type": "",
      "file_size": 0,
      "by": "issuer",
      "hidden": false,
      "created_at": "2026-03-15T10:31:12.204118Z",
      "updated_at": "2026-03-15T10:31:12.204118Z",
      "source": "api",
      "hidden_at": null,
      "removed": false,
      "removed_at": null
    },
    {
      "id": "Hq4nW7cZ1bYt6eXa",
      "kind": "file",
      "title": "Final assessment report",
      "narrative": "",
      "url": "",
      "host": "",
      "href": "https://hyperstack.id/credential/6f1c2a8e-3b4d-4e5f-9a7b-1c2d3e4f5a6b/evidence/Hq4nW7cZ1bYt6eXa",
      "file_name": "final-assessment.pdf",
      "file_type": "application/pdf",
      "file_size": 2516000,
      "by": "issuer",
      "hidden": false,
      "created_at": "2026-03-15T10:32:40.918331Z",
      "updated_at": "2026-03-15T10:32:40.918331Z",
      "source": "studio",
      "hidden_at": null,
      "removed": false,
      "removed_at": null
    },
    {
      "id": "pR8sK2vN5mJd3gLf",
      "kind": "link",
      "title": "My portfolio",
      "narrative": "",
      "url": "https://www.behance.net/janedoe",
      "host": "behance.net",
      "href": "https://www.behance.net/janedoe",
      "file_name": "",
      "file_type": "",
      "file_size": 0,
      "by": "recipient",
      "hidden": true,
      "created_at": "2026-03-18T08:02:15.661204Z",
      "updated_at": "2026-03-19T14:20:03.120775Z",
      "source": "wallet",
      "hidden_at": "2026-03-19T14:20:03.118402Z",
      "removed": false,
      "removed_at": null
    }
  ],
  "can_add": true,
  "can_add_file": true,
  "can_add_reason": null,
  "used_bytes": 2516000,
  "limits": {
    "issuer_items": 10,
    "recipient_items": 5,
    "title_chars": 120,
    "text_chars": 2000,
    "url_chars": 2000,
    "file_bytes": 10485760,
    "storage_bytes": 5368709120,
    "file_types": [".jpeg", ".jpg", ".pdf", ".png", ".webp"]
  }
}

array

The items, in the shape of Item fields.

boolean

true when you can add an item now.

boolean

true when you can add a file now.

string | null

Why you can’t add:

plan: your plan has no credential evidence.
limit_items: the credential has 10 items from you.
revoked: the credential is revoked.
storage_full: your file storage is full. can_add stays true: you can still add links and text.

null when you can add anything.

integer

The size of all evidence files of your organization and its departments, in bytes. They share 5 GB.

object

The limits, as numbers: items per credential (issuer_items, recipient_items), characters (title_chars, text_chars, url_chars), bytes (file_bytes, storage_bytes) and the file endings Hyperstack takes (file_types).

Add evidence

POST https://api.thehyperstack.com/v1/credential/{document_id}/evidence

Adds one item from your organization. Send JSON for a link or a text. Send multipart/form-data for a file. You can add evidence to a credential under review or published. Viewers see it once the credential is published. You can’t add to a revoked credential.

Body Parameters

string

required

The item’s title, up to 120 characters. For a file you can leave it out: the title is then the file name without its ending.

string

A link, up to 2,000 characters. It must start with https:// or http://. Send it for a link item. Hyperstack never opens the link.

string

Plain text, up to 2,000 characters. It is the text of a text item, so a text item needs it. For a link or a file it is an optional description.

file

A file, up to 10 MB: PDF, PNG, JPEG or WebP. Hyperstack checks the file’s ending and its first bytes. Send it as multipart/form-data. Don’t send a url with it.

A link item has url, a text item has only narrative, and a file item has file.

curl -X POST "https://api.thehyperstack.com/v1/credential/6f1c2a8e-3b4d-4e5f-9a7b-1c2d3e4f5a6b/evidence" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Capstone project repo",
    "url": "https://github.com/janedoe/stockroom",
    "narrative": "The app'\''s code, with a README that explains how to run it."
  }'

curl -X POST "https://api.thehyperstack.com/v1/credential/6f1c2a8e-3b4d-4e5f-9a7b-1c2d3e4f5a6b/evidence" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Assessor'\''s note",
    "narrative": "Jane planned and ran a two-week sprint with four other learners."
  }'

curl -X POST "https://api.thehyperstack.com/v1/credential/6f1c2a8e-3b4d-4e5f-9a7b-1c2d3e4f5a6b/evidence" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "title=Final assessment report" \
  -F "file=@final-assessment.pdf"

The answer is 201 with the new item and the new add state:

201 Created

{
  "success": true,
  "item": {
    "id": "k3T9vQx2LmP8sR4w",
    "kind": "link",
    "title": "Capstone project repo",
    "narrative": "The app's code, with a README that explains how to run it.",
    "url": "https://github.com/janedoe/stockroom",
    "host": "github.com",
    "href": "https://github.com/janedoe/stockroom",
    "file_name": "",
    "file_type": "",
    "file_size": 0,
    "by": "issuer",
    "hidden": false,
    "created_at": "2026-03-15T10:31:12.204118Z",
    "updated_at": "2026-03-15T10:31:12.204118Z",
    "source": "api",
    "hidden_at": null,
    "removed": false,
    "removed_at": null
  },
  "can_add": true,
  "can_add_file": true,
  "can_add_reason": null,
  "used_bytes": 2516000
}

Delete evidence

DELETE https://api.thehyperstack.com/v1/credential/{document_id}/evidence/{evidence_id}

Deletes one of your items, file included. This can’t be undone. You can’t delete an item the recipient added: hide it in the Studio instead. You can’t delete items of a revoked credential.

curl -X DELETE "https://api.thehyperstack.com/v1/credential/6f1c2a8e-3b4d-4e5f-9a7b-1c2d3e4f5a6b/evidence/k3T9vQx2LmP8sR4w" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 Success

{
  "success": true,
  "can_add": true,
  "can_add_file": true,
  "can_add_reason": null,
  "used_bytes": 2516000
}

Errors

Errors have the usual error body:

{
  "success": false,
  "error": "Your plan doesn't include evidence. Upgrade to add it.",
  "error_code": "feature_unavailable"
}

Error code	Status	When
`title_required`	400	Add: no `title` (link and text items).
`title_too_long`	400	Add: the title is over 120 characters.
`invalid_url`	400	Add: the link is not a full `https://` or `http://` link, or you sent a link and a file.
`text_required`	400	Add: no `url`, no `file` and no `narrative`.
`text_too_long`	400	Add: the text is over 2,000 characters.
`file_type`	400	Add: the file is not a PDF, PNG, JPEG or WebP file.
`invalid_evidence`	400	Add: `title`, `url` or `narrative` is not text.
`feature_unavailable`	403	Add: your plan has no credential evidence.
`limit_items`	403	Add: the credential has 10 items from you.
`storage_full`	403	Add: your 5 GB of evidence files is full. Links and text still work.
`not_allowed`	403	Add or delete on a revoked credential, or delete of an item the recipient added.
`credential_not_found`	404	No credential with this key in your organization.
`evidence_not_found`	404	Delete: no item with this ID on the credential.
`too_large`	413	Add: the file is over 10 MB.

A missing or wrong API key returns 403 with {"detail": "Invalid token or organization not found"}.

API Guide

Credential Groups

Credentials

Recipients

Webhooks

Standards and AI

Before you start

Item fields

List evidence

Add evidence

Body Parameters

Delete evidence

Errors

​Before you start

​Item fields

​List evidence

​Add evidence

​Body Parameters

​Delete evidence

​Errors

Before you start

Item fields

List evidence

Add evidence

Body Parameters

Delete evidence

Errors