Eraser

https://docs.eraser.io/
Admin
Eraser is a docs and diagrams platform for engineering teams, enabling developers to create visual...
Tokens:118,504
Snippets:1,078
Trust Score:9.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example response for Get a folder

Source: https://docs.eraser.io/reference/get-folder

Example response for a successful GET request to the folder endpoint. Shows the folder object with fields like id, name, order, teamId, createdBy, timestamps, and parentFolderId.

```json
{
  "id": "xK9mPq2vR",
  "name": "Design Docs",
  "order": 0,
  "teamId": "tN4wLm8jY",
  "createdBy": "uB7cHd3sW",
  "createdAt": "2025-07-01T12:00:00.000Z",
  "updatedAt": "2025-07-15T09:30:00.000Z",
  "parentFolderId": null
}
```

--------------------------------

### Example response for get file

Source: https://docs.eraser.io/reference/get-file

Shows the JSON structure returned by the API, including file metadata and content with elements and document.

```json
{
  "id": "abc123",
  "fileUrl": "https://app.eraser.io/workspace/abc123",
  "title": "My File",
  "author": "user-id-1",
  "folderId": null,
  "createdAt": "2025-07-01T12:00:00.000Z",
  "updatedAt": "2025-07-15T09:30:00.000Z",
  "linkAccess": "no-link-access",
  "content": {
    "elements": [
      {
        "id": "elem1",
        "type": "diagram",
        "diagramType": "sequence-diagram",
        "code": "A > B: Hello",
        "x": 0,
        "y": 0,
        "width": 400,
        "height": 300
      }
    ],
    "document": "# Hello\n\nThis is a test."
  }
}
```

--------------------------------

### Example response - list folders

Source: https://docs.eraser.io/reference/list-folders

Example JSON response showing a folder object with fields like id, name, order, teamId, createdBy, and timestamps.

```json
[
  {
    "id": "xK9mPq2vR",
    "name": "Design Docs",
    "order": 0,
    "teamId": "tN4wLm8jY",
    "createdBy": "uB7cHd3sW",
    "createdAt": "2025-07-01T12:00:00.000Z",
    "updatedAt": "2025-07-15T09:30:00.000Z",
    "parentFolderId": null
  }
]
```

--------------------------------

### Create a diagram in a file - Example response

Source: https://docs.eraser.io/reference/create-diagram

This is the example response returned when a diagram is successfully created. It includes the diagram ID, URL, type, code, and updated timestamp.

```json
{
  "id": "diag2",
  "diagramUrl": "https://app.eraser.io/workspace/abc123?diagram=diag2&layout=canvas",
  "diagramType": "flowchart-diagram",
  "code": "Start > End",
  "updatedAt": "2025-07-15T09:30:00.000Z"
}
```

--------------------------------

### Example request: curl to list files

Source: https://docs.eraser.io/reference/list-files

Sends a GET request to the Eraser API to list files, with query parameters limit=2 and sort=-updatedAt. Requires an Authorization header with a bearer token.

```bash
curl --location 'https://app.eraser.io/api/files?limit=2&sort=-updatedAt' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE'
```

--------------------------------

### 200 response schema example

Source: https://docs.eraser.io/reference/list-files

Example of the 200 response body, showing the structure with a files array and nextCursor. Note that folderId is omitted in this example.

```json
{
  "files": [
    {
      "id": "string",
      "fileUrl": "https://app.eraser.io/workspace/abc123",
      "title": "System Architecture",
      "author": "string",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "linkAccess": "no-link-access"
    }
  ]
}
```

--------------------------------

### Example response

Source: https://docs.eraser.io/reference/create-file

Shows the JSON response for a successful file creation.

```json
{
  "id": "abc123",
  "fileUrl": "https://app.eraser.io/workspace/abc123",
  "title": "My File",
  "author": "api",
  "folderId": null,
  "createdAt": "2025-07-15T09:30:00.000Z",
  "updatedAt": "2025-07-15T09:30:00.000Z",
  "linkAccess": "no-link-access",
  "content": {
    "elements": [],
    "document": "# Hello\n\nThis is a test."
  }
}
```

--------------------------------

### Stripe Payment Flow Example

Source: https://docs.eraser.io/docs/creating-a-new-ai-diagram

This example shows a complete Stripe payment flow with three files: server.rb (Sinatra backend), checkout.html (frontend form), and checkout.js (client-side logic). It demonstrates creating a PaymentIntent and handling payment with Stripe Elements.

```ruby
// Source: https://stripe.com/docs/payments/quickstart

// server.rb

require 'sinatra'
require 'stripe'
# This is a public sample test API key.
# Don’t submit any personally identifiable information in requests made with this key.
# Sign in to see your own test API key embedded in code samples.
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

set :static, true
set :port, 4242

# Securely calculate the order amount
def calculate_order_amount(_items)
  # Replace this constant with a calculation of the order's amount
  # Calculate the order total on the server to prevent
  # people from directly manipulating the amount on the client
  1400
end

# An endpoint to start the payment process
post '/create-payment-intent' do
  content_type 'application/json'
  data = JSON.parse(request.body.read)

  # Create a PaymentIntent with amount and currency
  payment_intent = Stripe::PaymentIntent.create(
    amount: calculate_order_amount(data['items']),
    currency: 'usd',
    automatic_payment_methods: {
      enabled: true,
    },
  )

  {
    clientSecret: payment_intent['client_secret']
  }.to_json
end
```

```html
// checkout.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Accept a payment</title>
    <meta name="description" content="A demo of a payment on Stripe" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="checkout.css" />
    <script src="https://js.stripe.com/v3/"></script>
    <script src="checkout.js" defer></script>
  </head>
  <body>
    <!-- Display a payment form -->
    <form id="payment-form">
      <div id="link-authentication-element">
        <!--Stripe.js injects the Link Authentication Element-->
      </div>
      <div id="payment-element">
        <!--Stripe.js injects the Payment Element-->
      </div>
      <button id="submit">
        <div class="spinner hidden" id="spinner"></div>
        <span id="button-text">Pay now</span>
      </button>
      <div id="payment-message" class="hidden"></div>
    </form>
  </body>
</html>
```

```javascript
// checkout.js

// This is a public sample test API key.
// Don’t submit any personally identifiable information in requests made with this key.
// Sign in to see your own test API key embedded in code samples.
const stripe = Stripe("pk_test_TYooMQauvdEDq54NiTphI7jx");

// The items the customer wants to buy
const items = [{ id: "xl-tshirt" }];

let elements;

initialize();
checkStatus();

document
  .querySelector("#payment-form")
  .addEventListener("submit", handleSubmit);

let emailAddress = '';
// Fetches a payment intent and captures the client secret
async function initialize() {
  const response = await fetch("/create-payment-intent", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ items }),
  });
  const { clientSecret } = await response.json();

  const appearance = {
    theme: 'stripe',
  };
  elements = stripe.elements({ appearance, clientSecret });

  const linkAuthenticationElement = elements.create("linkAuthentication");
  linkAuthenticationElement.mount("#link-authentication-element");

  linkAuthenticationElement.on('change', (event) => {
    emailAddress = event.value.email;
  });

  const paymentElementOptions = {
    layout: "tabs",
  };

  const paymentElement = elements.create("payment", paymentElementOptions);
  paymentElement.mount("#payment-element");
}

async function handleSubmit(e) {
  e.preventDefault();
  setLoading(true);
```

--------------------------------

### Example usage metrics response

Source: https://docs.eraser.io/reference/get-usage-metrics

Example JSON response returned by the usage metrics endpoint. Shows the date range, aggregate team statistics, and per-member activity for the requested period.

```json
  {  
    "range": {  
      "start": "2025-07-01",  
      "end": "2025-07-31"  
    },  
    "aggregate": {  
      "teamName": "Enterprise architecture",  
      "totalMembers": 60,  
      "activeMembers": 50,  
      "inactiveMembers": 10,  
      "totalFiles": 100,  
      "totalFilesCreated": 34,  
      "totalFilesViewed": 43,  
      "totalFileViews": 1234,  
      "totalAiCreditsUsed": 1234  
    }  
  }
```

--------------------------------

### Update a file - Example response

Source: https://docs.eraser.io/reference/update-file

This is the JSON response returned after successfully updating a file.

```json
{
  "id": "abc123",
  "fileUrl": "https://app.eraser.io/workspace/abc123",
  "title": "Updated Title",
  "author": "user-id-1",
  "folderId": null,
  "createdAt": "2025-07-01T12:00:00.000Z",
  "updatedAt": "2025-07-15T10:00:00.000Z",
  "linkAccess": "no-link-access",
  "content": {
    "elements": [],
    "document": "# Updated Content"
  }
}
```

--------------------------------

### Sequence diagram example with alt/else and activation

Source: https://docs.eraser.io/sequence-diagram-examples

Sequence diagram example in Eraser's diagram-as-code syntax. Shows a transaction flow between Web App, DB, Cloud Fx, and API, including an alt/else block for success and failure paths, and activation/deactivation of the API to represent ongoing events.

```eraser
Web App [icon: layout] > DB [icon: database]: Start transaction
Web App > Cloud Fx [icon: function]: Call function
Cloud Fx > API [icon: cloud-cog]: Create session
API > Cloud Fx: Session info
Cloud Fx > DB: Create tx record
Cloud Fx > API: Request access token
API > Cloud Fx: Access token
Cloud Fx > Web App: Token and transaction info
Web App > API: Complete transaction
alt [label: If successful]{
  API > Web App: Transaction confirmation
}
else [label: If failed]{
  API > Web App: Transaction cancellation
}
Web App > DB: Create tx record
Web App > API: Subscribe to transaction changes
activate API 
API > API: Ongoing events
API > Web App: Push events
deactivate API
```

--------------------------------

### GET /api/files

Source: https://docs.eraser.io/reference/list-files

This snippet documents the GET /api/files endpoint, including its query parameters, request example, response schema, and error codes.

```APIDOC
## GET /api/files

### Description
Retrieves a paginated list of files from the Eraser workspace. Supports filtering by team, folder, author, and sorting.

### Method
GET

### Endpoint
https://app.eraser.io/api/files

### Parameters
#### Query Parameters
- **teamId** (string) - Optional - The team to act on. Required with an organization API token; team tokens can omit it.
- **limit** (integer) - Optional - Maximum number of files to return (1-500). Defaults to 100.
- **cursor** (string) - Optional - Cursor for pagination. Use `nextCursor` from a previous response.
- **folderId** (string) - Optional - Filter files by folder ID.
- **sort** (string) - Optional - Sort field with optional `-` prefix for descending order. Defaults to `-updatedAt`. Allowed values: `createdAt`, `-createdAt`, `updatedAt`, `-updatedAt`.
- **author** (string) - Optional - Filter by author (user ID or email address).

### Request Example
```
curl --location 'https://app.eraser.io/api/files?limit=2&sort=-updatedAt' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE'
```

### Response
#### Success Response (200)
- **files** (object[]) - Required - Array of files in the current page.
  - **id** (string) - Required - Unique identifier for the file.
  - **fileUrl** (string) - Required - URL to view the file in Eraser.
  - **title** (string) - Required - Title of the file.
  - **author** (string) - Required - User ID of the file author.
  - **folderId** (string | null) - Required - ID of the folder containing the file, or null if not in a folder.
  - **createdAt** (string) - Required - ISO 8601 timestamp of when the file was created.
  - **updatedAt** (string) - Required - ISO 8601 timestamp of when the file was last updated.
  - **linkAccess** (string) - Required - Current link access setting for the file. Allowed values: `no-link-access`, `anyone-with-link-can-edit`, `publicly-viewable`, `publicly-editable`, `sso-readable`, `sso-editable`.
- **nextCursor** (string | null) - Required - Cursor for the next page of results, or null if there are no more results.

#### Response Example
```
{
  "files": [
    {
      "id": "abc123",
      "fileUrl": "https://app.eraser.io/workspace/abc123",
      "title": "System Architecture",
      "author": "user-id-1",
      "folderId": null,
      "createdAt": "2025-07-01T12:00:00.000Z",
      "updatedAt": "2025-07-15T09:30:00.000Z",
      "linkAccess": "no-link-access"
    }
  ],
  "nextCursor": "abc123"
}
```

### Error Handling
- **400** - Invalid request parameters (e.g., invalid sort field, non-numeric limit, invalid cursor).
- **401** - Missing or invalid bearer token.
- **403** - Unauthorized.
- **500** - Internal server error.
```

--------------------------------

### Example request: curl GET diagram

Source: https://docs.eraser.io/reference/get-diagram

Sends a GET request to the Eraser API to retrieve a diagram. Requires a bearer token for authorization.

```bash
curl --location 'https://app.eraser.io/api/files/abc123/diagrams/diag1' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE'
```

--------------------------------

### Example response

Source: https://docs.eraser.io/reference/create-folder

The response body for a successful folder creation, containing the created folder's ID.

```json
{
  "id": "xK9mPq2vR"
}
```

--------------------------------

### Example response: paginated list of files

Source: https://docs.eraser.io/reference/list-files

Shows a sample response from the list files endpoint, containing a files array with one file object and a nextCursor for pagination.

```json
{
  "files": [
    {
      "id": "abc123",
      "fileUrl": "https://app.eraser.io/workspace/abc123",
      "title": "System Architecture",
      "author": "user-id-1",
      "folderId": null,
      "createdAt": "2025-07-01T12:00:00.000Z",
      "updatedAt": "2025-07-15T09:30:00.000Z",
      "linkAccess": "no-link-access"
    }
  ],
  "nextCursor": "abc123"
}
```

--------------------------------

### 200 response example for GET /api/teams

Source: https://docs.eraser.io/reference/list-teams

Shows the JSON structure returned when the request succeeds. The organization object is null for team tokens and set for organization API tokens. The teams array contains objects with id, name, and createdAt fields.

```json
{
  "organization": {
    "id": "string",
    "name": "string"
  },
  "teams": [
    {
      "id": "string",
      "name": "string",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}
```

--------------------------------

### GET /files/{fileId}/diagrams/{diagramId}

Source: https://docs.eraser.io/reference/create-file

Gets a diagram by ID.

```APIDOC
## GET /files/{fileId}/diagrams/{diagramId}

### Description
Gets a diagram by ID.

### Method
GET

### Endpoint
/files/{fileId}/diagrams/{diagramId}

### Parameters
#### Path Parameters
- **fileId** (string) - Required - The ID of the file.
- **diagramId** (string) - Required - The ID of the diagram.

### Response
#### Success Response (200)
- **diagram** (object) - The diagram data.

#### Response Example
{
  "diagram": {}
}
```

--------------------------------

### POST /render

Source: https://docs.eraser.io/reference/create-file

Generates a diagram from a prompt using AI.

```APIDOC
## POST /render

### Description
Generates a diagram from a prompt using AI.

### Method
POST

### Endpoint
/render

### Request Body
- **prompt** (string) - Required - The prompt describing the diagram to generate.

### Response
#### Success Response (200)
- **diagram** (object) - The generated diagram data.

#### Response Example
{
  "diagram": {}
}
```

--------------------------------

### 200 response schema for Get a folder

Source: https://docs.eraser.io/reference/get-folder

Schema for the 200 response of the Get a folder endpoint. Shows the expected structure with placeholder values for each field.

```json
{
  "id": "string",
  "name": "string",
  "order": 0,
  "teamId": "string",
  "createdBy": "string",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

--------------------------------

### Arrow color property examples

Source: https://docs.eraser.io/sequence-diagram-syntax

Two examples of setting the color property on an arrow. The first adds a label and color, the second only sets the color.

```eraser
Web App > DB: Start transaction [color: blue]
```

```eraser
Web App > DB: [color: blue]
```

--------------------------------

### Create a folder with curl

Source: https://docs.eraser.io/reference/create-folder

Creates a folder named 'Design Docs' at the root level. Requires a bearer token; team tokens can omit teamId, but organization tokens require it.

```bash
curl --location 'https://app.eraser.io/api/folders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
  "name": "Design Docs"
}'
```

--------------------------------

### Example response with returnAs url

Source: https://docs.eraser.io/reference/export-diagram

Shows the JSON response when returnAs is "url". The response contains the format and the public URL of the stored export.

```json
{
  "format": "png",
  "url": "https://IMAGE-SITE-URL/IMAGE-NAME.png"
}
```

--------------------------------

### Styling properties syntax examples

Source: https://docs.eraser.io/sequence-diagram-syntax

Syntax examples for diagram-level styling properties: colorMode, styleMode, typeface, and autoNumber. Each property has a default value and a set of allowed values.

```eraser
colorMode bold
```

```eraser
styleMode shadow
```

```eraser
typeface clean
```

```eraser
autoNumber on
```

--------------------------------

### Create a file with diagram elements using curl

Source: https://docs.eraser.io/reference/create-file

Creates a file with a diagram element. Requires a bearer token.

```bash
curl --location 'https://app.eraser.io/api/files' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
    "title": "Diagram File",
    "elements": [
        {
            "type": "diagram",
            "diagramType": "sequence-diagram",
            "code": "A > B: Hello"
        }
    ]
}'
```

--------------------------------

### POST /folders

Source: https://docs.eraser.io/reference/list-files

Creates a new folder.

```APIDOC
## POST /folders

### Description
Creates a new folder.

### Method
POST

### Endpoint
/folders

### Parameters
#### Request Body
- **name** (string) - Required - The name of the folder.
- **parentId** (string) - Optional - The ID of the parent folder.

### Request Example
{
  "name": "My Folder"
}

### Response
#### Success Response (200)
- **folder** (object) - The created folder object.

#### Response Example
{
  "folder": {}
}
```

--------------------------------

### Install Eraser Agent Skills

Source: https://docs.eraser.io/using-ai-agent-integrations

Run this command to install the Eraser skill for your AI coding agent. Works with Claude Code, Cursor, and other agents that support the skills framework.

```bash
npx skills install eraserlabs/eraser-io
```

--------------------------------

### List folders - basic request

Source: https://docs.eraser.io/reference/list-folders

Sends a GET request to list folders. Requires an Authorization header with a bearer token.

```bash
curl --location 'https://app.eraser.io/api/folders' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE'
```

--------------------------------

### Example response for Retrieve AI request

Source: https://docs.eraser.io/reference/retrieve-ai-request

Example JSON response from the Retrieve AI request endpoint. It includes the original inputs and generated outputs such as diagram code, metadata, and a rendered image URL.

```json
{
  "id": "abc123def456",
  "inputs": [
    {
      "type": "text",
      "text": "Create a sequence diagram for a user authentication flow with 2FA"
    }
  ],
  "outputs": [
    {
      "type": "diagram",
      "diagramType": "sequence-diagram",
      "diagramTitle": "User Authentication with 2FA",
      "code": "User -> Login Page: Navigate\nLogin Page -> Auth Server: Submit credentials\nAuth Server -> User: Request 2FA code\nUser -> Auth Server: Submit 2FA\nAuth Server -> User: Return JWT token",
      "imageUrl": "https://IMAGE-URL"
    }
  ]
}
```

--------------------------------

### GET /teams

Source: https://docs.eraser.io/reference/create-file

Lists all teams.

```APIDOC
## GET /teams

### Description
Lists all teams.

### Method
GET

### Endpoint
/teams

### Response
#### Success Response (200)
- **teams** (array) - List of teams.

#### Response Example
{
  "teams": []
}
```
Tokens:
Raw