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

# API Overview

> Complete overview of TimeLockData API endpoints for evidence management and provable data integrity

The TimeLockData API provides endpoints for managing evidences -- cryptographically anchored records that prove specific data existed in a specific state at a specific time -- with full traceability on the blockchain.

## Base URL

```
https://api.timelockdata.com/api/v1
```

## Authentication

All requests require an API Key passed in the `X-API-Key` header.

```http theme={null}
X-API-Key: your_api_key
```

See [Authentication](/authentication) for details.

## Endpoint Groups

### Health

| Endpoint | Method | Description      | Auth |
| -------- | ------ | ---------------- | ---- |
| `/test`  | GET    | API health check | None |

### Categories

| Endpoint                                               | Method | Description          |
| ------------------------------------------------------ | ------ | -------------------- |
| `/evidences/{COMPANY_ID}/category`                     | POST   | Create a category    |
| `/evidences/{COMPANY_ID}/category`                     | GET    | List all categories  |
| `/evidences/{COMPANY_ID}/category/{CATEGORY_ID}`       | GET    | Get category details |
| `/evidences/{COMPANY_ID}/category/{CATEGORY_ID}`       | PUT    | Update a category    |
| `/evidences/{COMPANY_ID}/category/{CATEGORY_ID}/files` | GET    | List category files  |

### Subcategories

| Endpoint                                                                            | Method | Description             |
| ----------------------------------------------------------------------------------- | ------ | ----------------------- |
| `/evidences/{COMPANY_ID}/category/{CATEGORY_ID}/subcategory`                        | POST   | Create a subcategory    |
| `/evidences/{COMPANY_ID}/category/{CATEGORY_ID}/subcategory/{SUBCATEGORY_ID}`       | GET    | Get subcategory details |
| `/evidences/{COMPANY_ID}/category/{CATEGORY_ID}/subcategory/{SUBCATEGORY_ID}`       | PUT    | Update a subcategory    |
| `/evidences/{COMPANY_ID}/category/{CATEGORY_ID}/subcategory/{SUBCATEGORY_ID}/files` | GET    | List subcategory files  |

### Evidences

| Endpoint                                                                                | Method | Description                          |
| --------------------------------------------------------------------------------------- | ------ | ------------------------------------ |
| `/evidences/{COMPANY_ID}/category/{CATEGORY_ID}/subcategory/{SUBCATEGORY_ID}/evidence`  | POST   | Create an evidence                   |
| `/evidences/{COMPANY_ID}/evidence`                                                      | POST   | Create with inline category creation |
| `/evidences/{COMPANY_ID}/category/{CATEGORY_ID}/subcategory/{SUBCATEGORY_ID}/evidences` | POST   | Create in batch                      |
| `/evidences/{COMPANY_ID}/evidences`                                                     | GET    | List evidences                       |
| `/evidences/{COMPANY_ID}/evidence/{EVIDENCE_EXTERNAL_ID}`                               | GET    | Get evidence details                 |
| `/evidences/{COMPANY_ID}/evidence/{EVIDENCE_EXTERNAL_ID}`                               | PUT    | Update an evidence                   |
| `/evidences/{COMPANY_ID}/evidence/{EVIDENCE_EXTERNAL_ID}/files`                         | GET    | List evidence files                  |
| `/evidences/{COMPANY_ID}/blockinfo`                                                     | POST   | Get blockchain statistics            |

### Files

| Endpoint                       | Method | Description           |
| ------------------------------ | ------ | --------------------- |
| `/evidences/{COMPANY_ID}/file` | POST   | Upload files          |
| `/evidences/{COMPANY_ID}/file` | GET    | Download a file       |
| `/evidences/{COMPANY_ID}/file` | DELETE | Delete a file         |
| `/file/{COMPANY_ID}/{FILE_ID}` | GET    | Retrieve file content |

### Verification (Public, no auth required)

| Endpoint                               | Method | Description                        |
| -------------------------------------- | ------ | ---------------------------------- |
| `/merkle/root/{txid}`                  | GET    | Get Merkle root for a transaction  |
| `/merkle/proof/{txid}`                 | GET    | Get Merkle proof for a transaction |
| `/merkle/validate`                     | POST   | Validate a Merkle proof            |
| `/merkle/verify/{evidenceId}`          | GET    | Verify an evidence record          |
| `/merkle/verify/{evidenceId}/{fileId}` | GET    | Verify a file                      |
| `/merkle/tsa/{batchId}`                | GET    | Download TSA token                 |

### Source Systems

| Endpoint                                 | Method | Description                |
| ---------------------------------------- | ------ | -------------------------- |
| `/sourceSystem/{COMPANY_ID}`             | GET    | List source systems        |
| `/sourceSystem/{COMPANY_ID}`             | POST   | Create a source system     |
| `/sourceSystem/{COMPANY_ID}/{SYSTEM_ID}` | PATCH  | Update a source system     |
| `/sourceSystem/{COMPANY_ID}/{SYSTEM_ID}` | DELETE | Delete a source system     |
| `/sourceSystem/{COMPANY_ID}/healthz`     | GET    | Source system health check |

## Content Types

* **JSON requests**: `Content-Type: application/json`
* **File uploads**: `Content-Type: multipart/form-data`

## HTTP Status Codes

| Code  | Description                    |
| ----- | ------------------------------ |
| `200` | Success (GET, PUT, DELETE)     |
| `201` | Created (POST)                 |
| `400` | Invalid request data           |
| `401` | Missing or invalid credentials |
| `403` | Insufficient permissions       |
| `404` | Resource not found             |
| `409` | Resource already exists        |

## Error Response Format

```json theme={null}
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

## Blockchain Integration

All evidence operations (create, update, transfer) are recorded on the blockchain providing:

* Immutable audit trails
* Cryptographic verification via Merkle proofs
* eIDAS qualified TSA (Time Stamp Authority) certified timestamps issued by a qualified third-party
* Independent verification without authentication
* Records remain verifiable even without TimeLockData