Documents API
Create, read and update your documents programmatically
The Documents API lets you create, read and update the documents you own.
These endpoints will be retired on January 31, 2027. See REST API for details.
Authentication
All endpoints require an API key in the Authorization header:
Authorization: your-api-keySee Authentication for how to create a key.
Endpoints
Get Document
Retrieve one of your documents by ID.
GET /api/document?id={documentId}Parameters:
Prop
Type
Response:
{
"id": "abc123",
"name": "My Diagram",
"content": "{ \"user\": \"John\" }",
"format": "json",
"owner_id": "user-uuid",
"visibility": "private",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T14:20:00Z"
}Create Document
Create a new document.
POST /api/document
Content-Type: application/json
{
"name": "My New Diagram",
"content": "{ \"user\": \"John\" }",
"format": "json",
"visibility": "private"
}Parameters:
Prop
Type
Response:
The new document opens at https://todiagram.com/editor?doc={id}.
{
"id": "abc123"
}Update Document
Update one of your documents. Send only the fields you want to change.
PUT /api/document
Content-Type: application/json
{
"id": "abc123",
"name": "Updated Name",
"content": "{ \"user\": \"Jane\" }",
"format": "json"
}Parameters:
Prop
Type
Documents imported from a URL are a read-only live view of their source, so changing their content or format returns 409. You can still rename them.
Response:
The response includes the document ID, which can be opened at: https://todiagram.com/editor?doc={id}.
{
"id": "29a6b4a22f4ab8c4bdaf24cc"
}Errors
Errors return a JSON body with the HTTP status and a message, or a list of problems for invalid requests.
| Status | When | Body |
|---|---|---|
400 | The request body is invalid | { "status": 400, "errors": [{ "field": "content", "message": "Content is required" }] } |
400 | GET without an id | { "status": 400, "message": "Document ID is required" } |
401 | The Authorization header is missing | { "status": 401, "message": "Missing authorization key" } |
401 | The API key is wrong | { "status": 401, "message": "Invalid authorization key" } |
404 | The document doesn't exist or isn't yours | { "status": 404, "message": "Document not found" } |
409 | Changing the content of a document imported from a URL | { "status": 409, "message": "This document is a read-only live view of a remote source." } |