---
title: Core Request API
description: This page covers the request lifecycle endpoints that are not
  already documented in the dedicated verification, manifest, delivery, appeals,
  audit, subject, and retention pages.
group: reference-api
---
> ⚠️ **Warning:** **Alpha**
> DSAR is currently in alpha. APIs, package surfaces, configuration, and documentation may change as the project evolves.

This page covers the request lifecycle endpoints that are not already documented
in the dedicated verification, manifest, delivery, appeals, audit, subject, and
retention pages.

## Shared Intake Payload

Request creation and capture use the same intake body:

* `jurisdiction` (string, required)
* `intakeSource` (object, required)
* `intakeSource.channel` (string, required)
* `intakeSource.rawText` (string, required)
* `intakeSource.receivedAt` (string, required)
* `intakeSource.contact` (string, optional)
* `intakeSource.sourceEvidence` (array, optional)
* `requestor` (object, optional)
* `requestor.type` (string, required when present)
* `requestor.name` (string, optional)
* `requestor.email` (string, optional)
* `requestor.relation` (string, optional)
* `authority` (object, optional)
* `authority.evidenceArtifacts` (array, required when present)
* `authority.status` (string, required when present)
* `authority.verifiedAt` (string, optional)
* `receivedAt` (string, optional)

`intakeSource.receivedAt` is the timestamp from the original external intake
channel and is required for provenance. The top-level `receivedAt` is the time
DSAR recorded or ingested the request and may be later than the intake-source
timestamp or omitted entirely.

## POST /requests

Create a request.

**Response (202):**

```json
{
	"id": "req-123",
	"receivedAt": "2026-01-01T00:00:00.000Z",
	"status": "received"
}
```

## POST /requests/capture

Capture intake and return due-date context immediately.

**Response (202):**

```json
{
	"dueAt": "2026-02-01T00:00:00.000Z",
	"id": "req-123",
	"receivedAt": "2026-01-01T00:00:00.000Z",
	"status": "received"
}
```

## GET /requests

List requests in the queue.

**Query parameters:**

* `limit` (number, optional)
* `offset` (number, optional)
* `status` (string, optional)
* `sortBy` (string, optional)
* `sortOrder` (string, optional)
* `atRiskDays` (number, optional)

**Response (200):**

```json
{
	"items": [],
	"limit": 25,
	"offset": 0,
	"sortBy": "receivedAt",
	"sortOrder": "desc",
	"total": 0
}
```

## GET /requests/:id

Return a request detail record.

**Response (200):**

```json
{
	"appeals": [],
	"authority": {
		"evidenceArtifacts": [],
		"status": "not_required"
	},
	"clockMode": "active",
	"dueAt": "2026-02-01T00:00:00.000Z",
	"id": "req-123",
	"receivedAt": "2026-01-01T00:00:00.000Z",
	"requestor": {
		"type": "subject"
	},
	"status": "in_progress"
}
```

## GET /requests/:id/timeline

Return the request timeline.

**Response (200):**

```json
{
	"events": [
		{
			"createdAt": "2026-01-01T00:00:00.000Z",
			"eventType": "request_created",
			"id": "evt-123",
			"payload": {}
		}
	],
	"requestId": "req-123"
}
```

## GET /requests/:id/clock/explain

Explain how DSAR calculated the current deadline.

The response includes the base deadline, final due date, policy pack/version,
extensions, pauses, and segmented legal-clock history.

**Response (200):**

```json
{
	"baseDeadline": "2026-01-31T00:00:00.000Z",
	"clock": {
		"clockMode": "receipt",
		"dueAt": "2026-02-05T00:00:00.000Z",
		"receivedAt": "2026-01-01T00:00:00.000Z",
		"segments": [
			{
				"actor": "system",
				"countsTowardDeadline": true,
				"from": "2026-01-01T00:00:00.000Z",
				"policyVersion": "1.0.0",
				"reason": "base",
				"to": "2026-01-31T00:00:00.000Z"
			}
		]
	},
	"extensions": [
		{
			"additionalDays": 5,
			"justification": "policy_extension"
		}
	],
	"finalDueAt": "2026-02-05T00:00:00.000Z",
	"pauses": [
		{
			"duration": "2 days",
			"reason": "verification"
		}
	],
	"policyPack": "gdpr-eu",
	"policyVersion": "1.0.0",
	"requestId": "req-123"
}
```

## Lifecycle Transition Endpoints

These endpoints all return the common lifecycle response shape:

```json
{
	"dueAt": "2026-02-01T00:00:00.000Z",
	"id": "req-123",
	"status": "in_progress"
}
```

### POST /requests/:id/clarifications/request

Pause progress and request clarification from the subject or requestor.

### POST /requests/:id/clarifications/receive

Record that the clarification was received and let the workflow continue.

### POST /requests/:id/extensions

Extend the legal deadline for the request.

### POST /requests/:id/refusals

Refuse the request.

**Request body:**

* `message` (string, optional)
* `rationale` (string, optional)
* `reason` (string, optional)

### POST /requests/:id/closures

Close the request.

### POST /requests/:id/acknowledgements

Record that the request was acknowledged.

## PUT /requests/:id/requestor

Replace or set the requestor snapshot.

**Request body:**

* `type` (string, required)
* `name` (string, optional)
* `email` (string, optional)
* `relation` (string, optional)

**Response (202):** Lifecycle response envelope.

## Authority Endpoints

Use these endpoints when a representative or agent must prove authority to act
for the data subject.

### POST /requests/:id/authority/submit

**Request body:**

* `evidenceArtifacts` (array, required)
* `status` (string, required)
* `verifiedAt` (string, optional)

### POST /requests/:id/authority/approve

Approve submitted authority evidence.

### POST /requests/:id/authority/reject

Reject submitted authority evidence.

All three endpoints return the lifecycle response envelope.

## Notification History

### GET /requests/:id/notifications

List notification events and delivery attempts for a request.

**Response (200):**

```json
{
	"events": [
		{
			"attempts": [
				{
					"attempt": 1,
					"channel": "email",
					"createdAt": "2026-01-01T00:00:00.000Z",
					"destination": "user@example.com",
					"status": "delivered"
				}
			],
			"createdAt": "2026-01-01T00:00:00.000Z",
			"eventId": "evt-123",
			"eventType": "request_fulfilled",
			"status": "delivered"
		}
	],
	"requestId": "req-123"
}
```

### POST /requests/:id/notifications/:eventId/replay

Replay one notification event.

**Response (202):**

```json
{
	"eventId": "evt-123",
	"status": "replayed"
}
```

## Related Pages

* [Verification API](./verification.md)
* [Manifest API](./manifest.md)
* [Delivery API](./delivery.md)
* [Appeals API](./appeals.md)
* [Audit API](./audit.md)
* [Request Lifecycle](../../guides/request-lifecycle.md)