Documents API

CRUD operations for JSON documents stored in Forge Json.

Base URL: /api/v1/documents Required permission: documents

List documents


GET /api/v1/documents

Query parameters

Parameter	Type	Default	Description
`limit`	number	50	Maximum documents to return
`cursor`	string	—	Pagination cursor from previous response
`folder`	string	—	Filter by folder path (e.g., `"My Folder/Subfolder"`)

Example


curl -X GET "https://forgejson.com/api/v1/documents?limit=10" \
  -H "Authorization: Bearer fje_your_key"

Response (200)


{
  "success": true,
  "documents": [
    {
      "id": "jd7abc123",
      "name": "users.json",
      "title": "users.json",
      "description": "User database export",
      "tags": ["production", "users"],
      "fileSize": 2048,
      "createdAt": 1708876800000,
      "updatedAt": 1708963200000
    }
  ],
  "nextCursor": "abc123def456"
}

Use nextCursor in the next request to fetch more results. When nextCursor is null, there are no more documents.

If the folder path does not exist, the API returns an empty list instead of an error.

Create a document


POST /api/v1/documents

Request body


{
  "name": "my-document.json",
  "content": { "hello": "world" },
  "description": "Optional description",
  "tags": ["tag1", "tag2"],
  "folder": "My Folder"
}

Field	Type	Required	Description
`name`	string	Yes	Document name (1–100 characters)
`content`	any JSON	Yes	The JSON content to store
`description`	string	No	Optional description
`tags`	string[]	No	Optional tags
`folder`	string \| null	No	Folder path (auto-creates folders)

Example


curl -X POST https://forgejson.com/api/v1/documents \
  -H "Authorization: Bearer fje_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "config.json", "content": {"debug": true, "port": 3000}}'

Response (201)


{
  "success": true,
  "document": {
    "id": "jd7xyz789",
    "name": "config.json",
    "title": "config.json",
    "tags": [],
    "fileSize": 34,
    "createdAt": 1708876800000,
    "updatedAt": 1708876800000
  }
}

File size is checked against your plan’s storage limit. If the document exceeds the limit, you’ll get a 413 error.

Get document metadata


GET /api/v1/documents/{id}

Example


curl -X GET https://forgejson.com/api/v1/documents/jd7abc123 \
  -H "Authorization: Bearer fje_your_key"

Response (200)


{
  "success": true,
  "document": {
    "id": "jd7abc123",
    "name": "users.json",
    "title": "users.json",
    "tags": ["production"],
    "fileSize": 2048,
    "createdAt": 1708876800000,
    "updatedAt": 1708963200000
  }
}

Download document content


GET /api/v1/documents/{id}/content

Returns the raw JSON content as a streaming response.

Example


curl -X GET https://forgejson.com/api/v1/documents/jd7abc123/content \
  -H "Authorization: Bearer fje_your_key" \
  -o output.json

Response headers


Content-Type: application/json
Content-Disposition: attachment; filename="users.json"
Content-Length: 2048

The body is the raw JSON content of the document.

Update document metadata


PUT /api/v1/documents/{id}

Request body


{
  "name": "renamed-document.json",
  "tags": ["updated", "v2"],
  "folder": "Archive"
}

All fields are optional, but at least one must be provided.

Field	Type	Description
`name`	string	New name (1–100 characters)
`description`	string	New description
`tags`	string[]	New tags (replaces existing)
`folder`	string \| null	New folder (`null` removes from folder)

Example


curl -X PUT https://forgejson.com/api/v1/documents/jd7abc123 \
  -H "Authorization: Bearer fje_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "users-v2.json", "tags": ["production", "v2"]}'

Update document content


PUT /api/v1/documents/{id}/content

Request body


{ "updated": true, "version": 2 }

Send the replacement JSON value as the entire request body. Do not wrap it in a content field.

Example


curl -X PUT https://forgejson.com/api/v1/documents/jd7abc123/content \
  -H "Authorization: Bearer fje_your_key" \
  -H "Content-Type: application/json" \
  -d '{"hello": "updated world"}'

Response (200)


{
  "success": true,
  "fileSize": 28
}

Delete a document


DELETE /api/v1/documents/{id}

This endpoint performs a soft delete. The response includes purgeAt, which tells you when the deleted document becomes eligible for permanent purge.

Example


curl -X DELETE https://forgejson.com/api/v1/documents/jd7abc123 \
  -H "Authorization: Bearer fje_your_key"

Response (200)


{
  "success": true,
  "deleted": true,
  "purgeAt": 1711468800000
}

Permanently purge a soft-deleted document


POST /api/v1/documents/{id}/purge

Use this endpoint only after the document has already been soft-deleted.

Example


curl -X POST https://forgejson.com/api/v1/documents/jd7abc123/purge \
  -H "Authorization: Bearer fje_your_key"

Response (200)


{
  "success": true,
  "deleted": true,
  "permanent": true
}

Error responses

Status	Meaning
`400`	Invalid request (missing fields, bad JSON, empty name)
`401`	Authentication failed
`403`	Missing `documents` permission
`404`	Document not found
`413`	Content exceeds storage limit
`429`	Rate limit exceeded
`500`	Internal server error