> ## Documentation Index
> Fetch the complete documentation index at: https://thehyperstack.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Credential Evidence

> List, add and delete the evidence of a credential: links, files and text that show the work behind it.

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](https://thehyperstack.com/docs/api-guide/open-badges.md#evidence) downloads. See [Credential evidence](https://thehyperstack.com/docs/tutorials/credential-setup/credential-evidence.md) for how it works in the Studio.

| Method | URL | Does |
| - | - | - |
| `GET` | `/v1/credential/{document_id}/evidence` | [Lists the evidence](#list-evidence) |
| `POST` | `/v1/credential/{document_id}/evidence` | [Adds one item](#add-evidence) |
| `DELETE` | `/v1/credential/{document_id}/evidence/{evidence_id}` | [Deletes one item](#delete-evidence) |

You can also send evidence when you issue: see the `evidence` field of [Issue Credential](https://thehyperstack.com/docs/api-guide/create-credential.md). [View Credential](https://thehyperstack.com/docs/api-guide/view-credential.md) 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:

**id** `string`

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

**kind** `string`

`link`, `file` or `text`.

**title** `string`

The item's title.

**narrative** `string`

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

**url** `string`

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

**host** `string`

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

**href** `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.

**file\_name** `string`

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

**file\_type** `string`

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

**file\_size** `integer`

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

**by** `string`

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

**hidden** `boolean`

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

**source** `string`

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

**hidden\_at** `string | null`

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

**removed** `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.

**removed\_at** `string | null`

When the recipient deleted it. `null` otherwise.

**created\_at** `string`

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

**updated\_at** `string`

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

## List evidence

```text theme={null}
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.

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

```json 200 Success theme={null}
{
  "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"]
  }
}
```

**items** `array`

The items, in the shape of [Item fields](#item-fields).

**can\_add** `boolean`

`true` when you can add an item now.

**can\_add\_file** `boolean`

`true` when you can add a file now.

**can\_add\_reason** `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.

**used\_bytes** `integer`

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

**limits** `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

```text theme={null}
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

**title** `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.

**url** `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.

**narrative** `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** `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`.

```bash Link theme={null}
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."
  }'
```

```bash Text theme={null}
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."
  }'
```

```bash File theme={null}
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:

```json 201 Created theme={null}
{
  "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

```text theme={null}
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.

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

```json 200 Success theme={null}
{
  "success": true,
  "can_add": true,
  "can_add_file": true,
  "can_add_reason": null,
  "used_bytes": 2516000
}
```

## Errors

Errors have the usual [error body](https://thehyperstack.com/docs/api-guide/errors.md#error-body):

```json theme={null}
{
  "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"}`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.