# List notifications

Returns the notifications addressed to the signed-in user, newest first. Page with `cursor`. Set `unread` to return only the ones with no `readAt`. Only a dashboard session can call this.

GET `/v1/notifications`

## Authorization

`Authorization` Bearer token · header required

`Authorization: Bearer <token>` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

## Query parameters

- `limit` integer required  
  min 1 · max 100 · default: 20
- `cursor` string  
  min length 1 · max length 4096
- `unread` boolean required  
  default: false

## Responses

### 200 Response for status 200

`$schema` string <uri>  
Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

`data` object[] required

Array of `object`

- `id` string required  
  min length 1
- `kind` string required  
  Allowed: `comment.created` `comment.replied` `thread.archived` `thread.unarchived` `mention`
- `teamId` string | any required  
  Team owning the Space this came from. Null when that Space has no team.
- `spaceId` string | any required  
  Space this came from. Null once that Space is gone.
- `threadId` string | any required  
  Comment thread this points at.
- `title` string required  
  One line naming what happened, ready to render.
- `body` string | any required  
  Text of the comment behind it. Null when the event carried none.
- `actor` object required  
  The person who acted. Every field is null when the commenter left no profile, as an anonymous one can.
  - `name` string | any required
  - `avatarUrl` string | any required
  - `color` string | any required
- `path` string | any required  
  Path inside the Space the thread is anchored to.
- `versionId` string | any required  
  Version the thread was opened against.
- `link` string | any required  
  Dashboard URL for the thread. Null when the Space has no team to address it under.
- `readAt` string <date-time> | any required  
  ISO 8601 timestamp when the notification was marked read. Null while it is unread.
- `createdAt` string <date-time> required  
  ISO 8601 timestamp when the notification was raised.

### pagination object required

- `nextCursor` string | any required  
  Cursor for the next page. Null on the last page.
- `hasMore` boolean required  
  True when another page exists.

### Error Response

`$schema` string <uri>  
Canonical JSON Schema URL for this response body.

- `type` string required
- `title` string required  
  Human-readable name of the error type. Derived from `code`.
- `status` integer required  
  HTTP status of the response, repeated in the body.
- `detail` string required
- `code` string required
- `pointer` string  
  RFC 6901 JSON Pointer to the request field or batch entry that failed, for example `/files/37/path`. Present on validation failures.
- `details` object  
  Machine-readable context keyed by the error code.
- `suggestions` string[]  
  Recovery steps safe to show to a person.
- `next` string[]  
  Commands or API requests to run next, usable as written.
- `requestId` string required  
  ID of this request, from the `X-Request-Id` header or generated. Quote it when contacting support.

## Try it

### Server

Base URL https://api.spacefast.com

### Authorization

Bearer token

## Parameters

- `limit` query * 
- `cursor` query
- `unread` query *

## Request Examples

### cURL
```bash
curl -X GET "https://api.spacefast.com/v1/notifications?limit=20&unread=false" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### JavaScript
```javascript
const response = await fetch("https://api.spacefast.com/v1/notifications?limit=20&unread=false", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});
```

### Python
```python
import requests

response = requests.get(
    "https://api.spacefast.com/v1/notifications?limit=20&unread=false",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)
```

### Response 200 default
```json
{
  "$schema": "http://example.com",
  "data": [
    {
      "id": "string",
      "kind": "comment.created",
      "teamId": "string",
      "spaceId": "string",
      "threadId": "string",
      "title": "string",
      "body": "string",
      "actor": {
        "name": "string",
        "avatarUrl": "string",
        "color": "string"
      },
      "path": "string",
      "versionId": "string",
      "link": "string",
      "readAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}
```

### Error Response Schema  
```json
{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}
```