Skip to content

docs: generate public API reference from OpenAPI spec #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nbouliol wants to merge 2 commits into
base: main
Choose a base branch
from
+2,257 −184
Open

docs: generate public API reference from OpenAPI spec #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
830b055
docs: generate public API endpoints from OpenAPI spec
nbouliol Jul 1, 2026
4c6d826
docs: restore notes pagination guidance (createdAt cursor)
nbouliol Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 1 addition & 27 deletions reference/api/endpoints/activity-logs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,11 @@
---
title: Activity Logs
description: "List activity logs for a project environment"
openapi: "/reference/api/openapi.json GET /v1/project/{projectName}/environment/{environmentName}/activity-logs"
---

## List activity logs

Returns activity logs for a specific project and environment, sorted by `createdAt` date in descending order (most recent first).

Use the `createdAt` filter for pagination.

```
GET /v1/project/{projectName}/environment/{environmentName}/activity-logs
```

### Authentication

All requests require a Bearer token in the `Authorization` header. Generate one from [your account settings](https://app.forestadmin.com/user-settings).

```
Authorization: Bearer YOUR_APPLICATION_TOKEN
```

<Warning>
The token must be generated by a user with an **Admin** role on the project. Tokens generated by non-admin users will not have access to this endpoint.
</Warning>

<Warning>
If your project uses SSO, the application token must be generated while logged in with SSO.
</Warning>

### Path parameters

| Parameter | Type | Description |
|---|---|---|
| `projectName` | string | Your project name |
| `environmentName` | string | The environment name (e.g., `production`, `staging`) |
27 changes: 1 addition & 26 deletions reference/api/endpoints/admin-logs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,7 @@
---
title: Admin Logs
description: "List admin logs for a project"
openapi: "/reference/api/openapi.json GET /v1/project/{projectName}/admin-logs"
---

## List admin logs

Returns admin logs for a specific project, sorted by `createdAt` date in descending order (most recent first).

Use the `createdAt` filter for pagination.

```
GET /v1/project/{projectName}/admin-logs
```

### Authentication

All requests require a Bearer token in the `Authorization` header. Generate one from [your account settings](https://app.forestadmin.com/user-settings).

```
Authorization: Bearer YOUR_APPLICATION_TOKEN
```

<Warning>
If your project uses SSO, the application token must be generated while logged in with SSO.
</Warning>

### Path parameters

| Parameter | Type | Description |
|---|---|---|
| `projectName` | string | Your project name |
137 changes: 6 additions & 131 deletions reference/api/endpoints/notes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,7 @@
---
title: Notes
description: "List notes and their messages for a project environment"
openapi: "/reference/api/openapi.json GET /v1/project/{projectName}/environment/{environmentName}/notes"
---
Comment thread
macroscopeapp[bot] marked this conversation as resolved.

## List notes

Returns notes and their messages for a specific project and environment, sorted by `id` in descending order (most recent first).

Use the `createdAt` filters for pagination.

```
GET /v1/project/{projectName}/environment/{environmentName}/notes
```

### Authentication

All requests require a Bearer token in the `Authorization` header. Generate one from [your account settings](https://app.forestadmin.com/user-settings).

```
Authorization: Bearer YOUR_APPLICATION_TOKEN
```

<Warning>
The token must be generated by a user with an **Admin** role on the project. Tokens generated by non-admin users will not have access to this endpoint.
</Warning>
Expand All @@ -29,114 +10,8 @@ Authorization: Bearer YOUR_APPLICATION_TOKEN
If your project uses SSO, the application token must be generated while logged in with SSO.
</Warning>

### Path parameters

| Parameter | Type | Description |
|---|---|---|
| `projectName` | string | The **case sensitive** project name |
| `environmentName` | string | The **case sensitive** environment name |

### Query parameters

| Parameter | Type | Description |
|---|---|---|
| `limit` | integer | Maximum number of notes to return. Between 1 and 100. Default is 10. |
| `userEmail` | string | Filter by the email of the user who created the note. |
| `userId` | integer | Filter by the id of the user who created the note. |
| `teamName` | string | Filter by team name. |
| `collectionName` | string | Filter by collection name (as defined in your schema). |
| `recordId` | string | Filter by the id of the record the note is attached to. |
| `createdAt.eq` / `.lt` / `.lte` / `.gt` / `.gte` | string (ISO 8601) | Filter by creation date. Use `.lt`/`.lte`/`.gt`/`.gte` for range queries and pagination. |
| `updatedAt.eq` / `.lt` / `.lte` / `.gt` / `.gte` | string (ISO 8601) | Filter by last update date. |
| `archivedAt.eq` / `.lt` / `.lte` / `.gt` / `.gte` | string (ISO 8601) | Filter by archive date. |

### Response

```json
{
"hasMore": false,
"parameters": {
"projectName": "Forest",
"environmentName": "Production",
"limit": 10
},
"data": [
{
"object": "note",
"id": 42,
"title": "THE TITLE",
"recordId": "10",
"createdAt": "2024-02-20T10:35:54.685Z",
"updatedAt": "2024-03-10T10:36:54.685Z",
"archivedAt": "2024-05-22T14:01:23.015Z",
"user": {
"object": "user",
"id": 1,
"username": "alice1",
"email": "alice@somewhere.com"
},
"environment": {
"object": "environment",
"name": "Production"
},
"team": {
"object": "team",
"name": "Operations"
},
"collection": {
"object": "collection",
"name": "client"
},
"messages": [
{
"object": "note-message",
"content": "<p>Needs to be verified</p>",
"createdAt": "2024-02-20T10:35:54.685Z",
"user": {
"object": "user",
"email": "alice@somewhere.com",
"id": 1,
"username": "alice"
}
},
{
"object": "note-message",
"content": "<p>Ok</p>",
"createdAt": "2024-02-20T11:15:32.461Z",
"user": {
"object": "user",
"email": "bob@somewhere.com",
"id": 1,
"username": "bob"
}
}
]
}
]
}
```

### Response fields

| Field | Type | Description |
|---|---|---|
| `hasMore` | boolean | Whether more notes are available after this set. |
| `data[].id` | integer | The note id. |
| `data[].title` | string | The note title. |
| `data[].recordId` | string | The id of the record the note is attached to. |
| `data[].createdAt` | string (ISO 8601) | When the note was created. |
| `data[].updatedAt` | string (ISO 8601) | When the note (or one of its messages) was last updated. |
| `data[].archivedAt` | string (ISO 8601) | When the note was archived, if applicable. |
| `data[].user` | object | The user who created the note (`id`, `username`, `email`). |
| `data[].environment` | object | The environment the note is attached to. |
| `data[].team` | object | The team the note is attached to. |
| `data[].collection` | object | The collection the note is attached to. Notes created on collections deleted before 2024-06-11 may be missing this field. |
| `data[].messages` | array | Messages within the note thread. Each has `content` (HTML), `createdAt`, and `user`. |

### Errors

| Status | Meaning |
|---|---|
| `429` | Too many requests. The response includes a `Retry-After` header indicating the number of seconds to wait. |
| `4XX` | Client error. Response body contains `code` and `message`. |
| `5XX` | Server error. Response body contains `code` and `message`. |
<Note>
Results are paginated. When `hasMore` is `true`, fetch the next page by
passing `createdAt.lt` set to the oldest `createdAt` in the current
response.
</Note>
Loading