# Infa External API

> Learn how to integrate with Infa programmatically using our REST API for design system data access.

Source: https://infa.ai/docs/api

The Infa External API provides access to your design system data, allowing you to integrate Infa with third-party tools and services. This feature is available on all paid Infa plans (Pro, Team and Enterprise).

## Overview

We at Infa designed this API for external integrations like Figma plugins, Coda packs, and custom applications. The API provides read-only access to your design system components, boards, and related data.

**Base URL**: `https://api.infa.ai/rest/v1/rpc/`

## Authentication

### API Key Requirements

The Infa External API requires two headers for authentication:

1. **`x-api-key`** - Your personal API key (generate from your [profile page](https://infa.ai/profile?tab=integrations))
2. **`apikey`** - Fixed value for all requests

#### Required Headers

```http title="Request Headers" {1-2}
x-api-key: your_personal_api_key_here
apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxjaHdvdnh4YmdjZHljYXFtZnRqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTcxMDczNDksImV4cCI6MjAzMjY4MzM0OX0.0EIrHDQZMihWRsQ8ke1uoP4e0seFBJxuxLqc0jIhQGA
Content-Type: application/json
```

**Important Notes**:

-   Replace `your_personal_api_key_here` with your actual API key from your profile
-   Use the `apikey` value exactly as shown above (same for everyone)
-   API keys currently provide read-only access to your account data

### Generating API Keys

1. Open [infa.ai/profile?tab=integrations](https://infa.ai/profile?tab=integrations) (your avatar → **Profile** → **Integrations**)
2. Go to the **Personal Access Tokens** section
3. Click **Generate New Token**
4. Click the token's **copy** button and store the key securely. The table shows only the first four characters (`abcd****`); that preview is not the key

**Note** We are working on write permissions as well. The generated API key has limited access to specific API endpoints. If you would like additional integrations or want to test more features with us, please reach out to us.

## Available Endpoints

The Infa API provides the following endpoints:

-   **User Information**: Get current user details
-   **Boards**: List all accessible boards
-   **Main Components**: Retrieve design system components
-   **Component Views**: Get component screenshots and code
-   **External Links**: Access component documentation links
-   **Screens**: Retrieve page structure and hierarchy
-   **Page Reports**: Get component coverage reports and metrics

### User Information

#### Get Current User (`me`)

Retrieve information about the authenticated user.

**Endpoint**: `GET /rest/v1/rpc/me`

**Response**:

```json title="Response Example"
[
    {
        "id": "user_uuid",
        "full_name": "John Doe",
        "email": "john@example.com",
        "profile_picture": "https://example.com/avatar.jpg"
    }
]
```

**Example Usage**:

```javascript title="example.js" {1-2,8-9}
const response = await fetch("https://api.infa.ai/rest/v1/rpc/me", {
    method: "GET",
    headers: {
        "x-api-key": "your_personal_api_key_here",
        apikey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxjaHdvdnh4YmdjZHljYXFtZnRqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTcxMDczNDksImV4cCI6MjAzMjY4MzM0OX0.0EIrHDQZMihWRsQ8ke1uoP4e0seFBJxuxLqc0jIhQGA",
        "Content-Type": "application/json",
    },
});
const user = await response.json();
```

### Boards

#### Get All Boards (`get_boards`)

Retrieve all boards accessible to the authenticated user.

**Endpoint**: `GET /rest/v1/rpc/get_boards`

**Response**:

```json title="Response Example"
[
    {
        "board_id": "board_uuid",
        "title": "Design System Components",
        "type": "cloud",
        "description": "Main design system board",
        "domain": "example.com",
        "created_at": "2024-01-15T10:30:00Z"
    }
]
```

**Example Usage**:

```javascript title="example.js" {1-2,10-11}
const response = await fetch("https://api.infa.ai/rest/v1/rpc/get_boards", {
    method: "GET",
    headers: {
        "x-api-key": "your_personal_api_key_here",
        apikey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxjaHdvdnh4YmdjZHljYXFtZnRqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTcxMDczNDksImV4cCI6MjAzMjY4MzM0OX0.0EIrHDQZMihWRsQ8ke1uoP4e0seFBJxuxLqc0jIhQGA",
        "Content-Type": "application/json",
    },
});
const boards = await response.json();
```

### Main Components

#### Get Main Components (`get_main_components`)

Retrieve main components, optionally filtered by board.

**Endpoint**: `GET /rest/v1/rpc/get_main_components`

**Parameters**:

-   `p_board_id` (optional): Filter components by specific board ID

**Response**:

```json title="Response Example"
[
    {
        "main_component_id": "component_uuid",
        "board_id": "board_uuid",
        "title": "Button Component",
        "description": "Primary button component with various states",
        "created_at": "2024-01-15T10:30:00Z"
    }
]
```

**Example Usage**:

```javascript title="example.js" {1-3,16-17}
// Get all components
const response = await fetch(
    "https://api.infa.ai/rest/v1/rpc/get_main_components",
    {
        method: "GET",
        headers: {
            "x-api-key": "your_personal_api_key_here",
            apikey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxjaHdvdnh4YmdjZHljYXFtZnRqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTcxMDczNDksImV4cCI6MjAzMjY4MzM0OX0.0EIrHDQZMihWRsQ8ke1uoP4e0seFBJxuxLqc0jIhQGA",
            "Content-Type": "application/json",
        },
    }
);

// Get components for specific board
const responseFiltered = await fetch(
    "https://api.infa.ai/rest/v1/rpc/get_main_components?p_board_id=board_uuid",
    {
        method: "GET",
        headers: {
            "x-api-key": "your_personal_api_key_here",
            apikey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxjaHdvdnh4YmdjZHljYXFtZnRqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTcxMDczNDksImV4cCI6MjAzMjY4MzM0OX0.0EIrHDQZMihWRsQ8ke1uoP4e0seFBJxuxLqc0jIhQGA",
            "Content-Type": "application/json",
        },
    }
);
```

### Component Views

#### Get Component Views (`get_component_views`)

Retrieve component views (screenshots and code examples), optionally filtered by board.

**Endpoint**: `GET /rest/v1/rpc/get_component_views`

**Parameters**:

-   `p_board_id` (optional): Filter views by specific board ID

**Response**:

```json title="Response Example"
[
    {
        "component_view_id": "view_uuid",
        "main_component_id": "component_uuid",
        "title": "Button Primary State",
        "x_path": "//button[@class='btn-primary']",
        "url": "https://example.com/components/button",
        "is_domain_specific": true,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "screenshot": "https://example.com/screenshots/button.png",
        "code": "<button class=\"btn-primary\">Click me</button>"
    }
]
```

### Storybook Usage Data

#### Get Components for Storybook (`get_storybook_main_components`)

What the [Storybook addon](https://www.npmjs.com/package/storybook-infa-usage) reads: the components you name, each with its views, labels, external links and the screens of its board. The addon's `npx infa-usage-fetch` command calls it for you.

**Endpoint**: `POST /rest/v1/rpc/get_storybook_main_components`

**Body**: `{ "p_mc_component_ids": ["mc_abc12345"] }`

```javascript title="example.js"
const response = await fetch(
    "https://api.infa.ai/rest/v1/rpc/get_storybook_main_components",
    {
        method: "POST",
        headers: {
            "x-api-key": "your_personal_api_key_here",
            apikey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxjaHdvdnh4YmdjZHljYXFtZnRqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTcxMDczNDksImV4cCI6MjAzMjY4MzM0OX0.0EIrHDQZMihWRsQ8ke1uoP4e0seFBJxuxLqc0jIhQGA",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ p_mc_component_ids: ["mc_abc12345"] }),
    }
);
const components = await response.json();
```

Components on boards the key's account does not own are left out of the answer.

### External Links

#### Get External Links (`get_external_links`)

Retrieve external links associated with components.

**Endpoint**: `GET /rest/v1/rpc/get_external_links`

**Response**:

```json title="Response Example"
[
    {
        "external_link_id": "link_uuid",
        "main_component_id": "component_uuid",
        "title": "Figma Design File",
        "url": "https://figma.com/file/...",
        "created_at": "2024-01-15T10:30:00Z"
    }
]
```

### Screens

#### Get Screens (`get_screens`)

Retrieve page structure data, optionally filtered by board.

**Endpoint**: `GET /rest/v1/rpc/get_screens`

**Parameters**:

-   `p_board_id` (optional): Filter screens by specific board ID

**Response**:

```json title="Response Example"
[
    {
        "screen_id": "page_uuid",
        "board_id": "board_uuid",
        "title": "Homepage",
        "url_pattern": "https://example.com/",
        "is_dynamic": false,
        "default_url": "https://example.com/",
        "screenshot": { "url": "https://example.com/screenshot.png" },
        "parent_screen_id": null,
        "created_at": "2024-01-15T10:30:00Z",
        "weight": 1,
        "variables": {}
    }
]
```

### Page Reports

#### Get Page Reports (`get_screen_reports`)

Retrieve page coverage reports with component breakdown and metrics, optionally filtered by board or page.

**Endpoint**: `GET /rest/v1/rpc/get_screen_reports`

**Parameters**:

-   `p_board_id` (optional): Filter reports by specific board ID
-   `p_screen_id` (optional): Filter reports by specific page ID

**Response**:

```json title="Response Example"
[
    {
        "id": "report_uuid",
        "screen_id": "page_uuid",
        "board_id": "board_uuid",
        "dom_coverage_ratio": 0.75,
        "real_estate_ratio": 0.82,
        "total_component_count": 45,
        "total_dom_elements": 320,
        "dom_component_coverage": 240,
        "total_visual_screen_area": 1920000,
        "visual_component_coverage": 1574400,
        "visual_coverage_percentage": 82.0,
        "snapshot_name": "Homepage - Desktop",
        "snapshot_description": "Full page coverage analysis for desktop viewport",
        "is_baseline": true,
        "viewport_width": 1920,
        "viewport_height": 1080,
        "device_type": "desktop",
        "user_agent": "Mozilla/5.0...",
        "component_breakdown": {
            "components": [
                {
                    "mainComponentId": "mc_12345678",
                    "name": "Header",
                    "area": 184320,
                    "exclusiveArea": 92160,
                    "componentViews": ["cv_12345678"],
                    "nestedInstances": 2,
                    "standaloneInstances": 1,
                    "containsComponents": ["mc_87654321"],
                    "containedBy": []
                }
            ],
            "hierarchy": {
                "rootComponents": ["mc_12345678"],
                "parentChildRelationships": [
                    {
                        "parent": "mc_12345678",
                        "child": "mc_87654321"
                    }
                ]
            }
        },
        "metadata": {
            "scan_duration_ms": 3250,
            "browser_version": "Chrome 120.0"
        },
        "created_at": "2024-01-15T10:30:00Z",
        "user_id": "user_uuid"
    }
]
```

**Example Usage**:

```javascript title="example.js" {1-3,16-17,30-31}
// Get all page reports
const response = await fetch(
    "https://api.infa.ai/rest/v1/rpc/get_screen_reports",
    {
        method: "GET",
        headers: {
            "x-api-key": "your_personal_api_key_here",
            apikey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxjaHdvdnh4YmdjZHljYXFtZnRqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTcxMDczNDksImV4cCI6MjAzMjY4MzM0OX0.0EIrHDQZMihWRsQ8ke1uoP4e0seFBJxuxLqc0jIhQGA",
            "Content-Type": "application/json",
        },
    }
);

// Get reports for specific board
const reportsByBoard = await fetch(
    "https://api.infa.ai/rest/v1/rpc/get_screen_reports?p_board_id=board_uuid",
    {
        method: "GET",
        headers: {
            "x-api-key": "your_personal_api_key_here",
            apikey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxjaHdvdnh4YmdjZHljYXFtZnRqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTcxMDczNDksImV4cCI6MjAzMjY4MzM0OX0.0EIrHDQZMihWRsQ8ke1uoP4e0seFBJxuxLqc0jIhQGA",
            "Content-Type": "application/json",
        },
    }
);

// Get reports for specific page
const reportsByPage = await fetch(
    "https://api.infa.ai/rest/v1/rpc/get_screen_reports?p_screen_id=page_uuid",
    {
        method: "GET",
        headers: {
            "x-api-key": "your_personal_api_key_here",
            apikey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxjaHdvdnh4YmdjZHljYXFtZnRqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MTcxMDczNDksImV4cCI6MjAzMjY4MzM0OX0.0EIrHDQZMihWRsQ8ke1uoP4e0seFBJxuxLqc0jIhQGA",
            "Content-Type": "application/json",
        },
    }
);
```

**Field Descriptions**:

-   **Coverage Metrics**:
    -   `dom_coverage_ratio`: Ratio of DOM elements covered by components (0-1)
    -   `real_estate_ratio`: Legacy field for visual coverage
    -   `visual_coverage_percentage`: Percentage of page area covered by components
-   **Component Counts**:
    -   `total_component_count`: Total number of component instances detected
    -   `total_dom_elements`: Total DOM elements on the page
    -   `dom_component_coverage`: Number of DOM elements within components
-   **Visual Metrics**:
    -   `total_visual_screen_area`: Total viewport area in pixels²
    -   `visual_component_coverage`: Area covered by components in pixels²
-   **Snapshot Information**:
    -   `snapshot_name`: User-defined name for this coverage snapshot
    -   `snapshot_description`: Detailed description of the snapshot
    -   `is_baseline`: Whether this is the baseline snapshot for comparison
-   **Viewport Details**:
    -   `viewport_width`: Browser viewport width in pixels
    -   `viewport_height`: Browser viewport height in pixels
    -   `device_type`: Device category (desktop, tablet, mobile)
    -   `user_agent`: Browser user agent string
-   **Component Breakdown**:
    -   `component_breakdown`: Detailed JSON structure of all components and their relationships
        -   `components`: Array of component details including area, nesting, and relationships
        -   `hierarchy`: Component parent-child relationship tree
-   **Metadata**: Additional scan and analysis information

## Troubleshooting

### "Invalid API key or API key not found" (code `P0001`)

The request reached Infa, but the `x-api-key` header did not hold one of your tokens:

-   **Header name**: the key goes in `x-api-key`. Not `Authorization: Bearer`, and not `apikey` (that one carries the fixed public value above).
-   **The whole key**: copy it with the copy button. The `abcd****` in the table is a masked preview.
-   **No whitespace**: a space or line break around the key (common when it is read from a file) makes it a different key.
-   **Still listed**: a revoked token stops working at once; generate a new one.

### 401 "Invalid API key" without a code

The `apikey` header is missing or altered. Copy the public value above exactly.

### "User does not have access to the specified board"

The key reads boards its own account owns. Check the `p_board_id` and which account generated the token.

## Next Steps

For a complete design system management experience, explore our other integrations:

-   [Chrome Extension](https://infa.ai/docs/chrome-extension)
-   [Figma Plugin](https://infa.ai/docs/figma-plugin)
-   [Coda Pack](https://infa.ai/docs/coda-pack)

Need help with API integration? Check out our [general documentation](https://infa.ai/docs/general) for additional guidance on managing your design system with Infa.
