# Blueprint Studio API — Full Reference

Complete documentation for all 35 API v1 endpoints.
Base URL: https://tools.blueprintstudio.ai

## Authentication

Include your API key in the Authorization header:

```
curl https://tools.blueprintstudio.ai/api/v1/assets \
  -H "Authorization: Bearer bp_live_your_api_key_here"
```

API keys start with `bp_live_` or `bp_test_`. Create keys via the API or in account settings.

## Rate Limits

| Tier | API Requests | Generations |
|------|-------------|-------------|
| Free | 100 / day | 25 / month |
| Pro | 5,000 / day | 1,000 / month |
| Team | 20,000 / day | 5,000 / month |

Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After` (on 429).

## Error Codes

| Status | Meaning |
|--------|---------|
| 400 | Bad request — check parameters |
| 401 | Invalid or missing API key |
| 403 | Forbidden — insufficient permissions |
| 404 | Resource not found |
| 429 | Rate limit exceeded — check Retry-After header |
| 500 | Server error |
| 503 | Service unavailable (e.g., AI service not configured) |

Error response format: `{ "error": "description" }`

## Generation

Generate brand assets, get prompt suggestions, and brainstorm ideas using AI.

### POST /api/v1/generate

**Generate a brand asset**

Generate a new brand asset image using AI. Uses the same generation pipeline as the web app — supports styles (with org/parent inheritance), multiple reference images, aspect ratio selection, and iterative refinement via parent assets with full thread history.

  Request Body:
    - prompt: string (required) — What to generate (e.g., "a coffee cup icon")
    - styleId: string — Style ID to apply. Omit for org/user default. Use "freestyle" for no style.
    - aspectRatio: string (default: 1:1, enum: 1:1 | 16:9 | 9:16 | 4:3 | 3:4 | 3:2 | 2:3 | 4:5 | 5:4 | 21:9) — Output aspect ratio.
    - highQuality: boolean (default: false) — Use higher quality model.
    - parentAssetId: string — Parent asset ID for iterative refinement. Thread history and style are inherited automatically.
    - referenceImages: array — Array of reference image URLs or base64 data URLs (max 5). Preferred over referenceImage.
    - referenceImage: string — Single reference image — base64 data URL or HTTP URL. Legacy; prefer referenceImages[].
    - temperature: number (default: 0.4) — Generation temperature. Lower = more consistent.
    - imageSize: string (default: 2K, enum: 1K | 2K | 4K) — Output image resolution.

  Response (200): Generated asset details with a public image URL (no expiry).
  ```json
  {
    "assetId": "uuid",
    "imageUrl": "https://...",
    "prompt": "a coffee cup icon",
    "styleId": "uuid",
    "aspectRatio": "1:1",
    "threadId": "uuid",
    "versionNumber": 1
  }
  ```

### POST /api/v1/generate/suggest

**Get prompt suggestions**

Generate AI-powered prompt suggestions for a given style. Useful for inspiring users or populating prompt libraries.

  Request Body:
    - styleId: string — Style to base suggestions on. Omit for generic suggestions.
    - count: number (default: 5) — Number of suggestions to return (1–10).

  Response (200): Array of prompt suggestion strings.
  ```json
  {
    "suggestions": [
      "a minimalist coffee cup icon",
      "an abstract mountain landscape",
      "a geometric pattern with warm tones"
    ]
  }
  ```

### POST /api/v1/generate/ideas

**Generate asset ideas**

Generate creative asset concept ideas for a given topic. Returns an array of idea descriptions.

  Request Body:
    - topic: string (required) — Topic to brainstorm ideas for.

  Response (200): Array of idea strings.
  ```json
  {
    "ideas": [
      "A series of icons representing different coffee brewing methods",
      "Illustrated scenes of a cozy coffee shop atmosphere"
    ]
  }
  ```

## Assets

List, retrieve, delete, favorite, share, and remove backgrounds from generated assets.

### GET /api/v1/assets

**List assets**

List generated assets with pagination. Results are scoped to the authenticated user or brand.

  Query Parameters:
    - styleId: string — Filter by style ID.
    - limit: number (default: 50) — Max results per page (max 100).
    - offset: number (default: 0) — Pagination offset.

  Response (200): Paginated asset list with public image URLs (no expiry).
  ```json
  {
    "assets": [{
      "id": "uuid",
      "prompt": "a coffee cup icon",
      "imageUrl": "https://...",
      "aspectRatio": "1:1",
      "highQuality": false,
      "fileSizeBytes": 245000,
      "createdAt": "2025-01-01T00:00:00Z",
      "styleId": "uuid",
      "threadId": "uuid",
      "versionNumber": 1
    }],
    "total": 42,
    "limit": 50,
    "offset": 0
  }
  ```

### GET /api/v1/assets/:id

**Get an asset**

Get a single asset by ID, including both view and download URLs.

  Path Parameters:
    - id: string (required) — Asset UUID.

  Response (200): Full asset details with public image URL and download URL (no expiry).
  ```json
  {
    "id": "uuid",
    "prompt": "a coffee cup icon",
    "enhancedPrompt": "...",
    "imageUrl": "https://...",
    "downloadUrl": "https://...",
    "aspectRatio": "1:1",
    "highQuality": false,
    "fileSizeBytes": 245000,
    "createdAt": "2025-01-01T00:00:00Z",
    "styleId": "uuid",
    "threadId": "uuid",
    "versionNumber": 1,
    "brandId": null
  }
  ```

### DELETE /api/v1/assets/:id

**Delete an asset**

Soft-delete an asset (sets is_deleted: true). The image file remains in storage.

  Path Parameters:
    - id: string (required) — Asset UUID.

  Response (200): Deletion confirmation.
  ```json
  { "deleted": true }
  ```

### POST /api/v1/assets/:id/favorite

**Toggle favorite**

Toggle or explicitly set the favorite status of an asset.

  Path Parameters:
    - id: string (required) — Asset UUID.

  Request Body:
    - favorite: boolean — Set explicitly, or omit to toggle.

  Response (200): Updated favorite state.
  ```json
  { "id": "uuid", "isFavorite": true }
  ```

### POST /api/v1/assets/:id/share

**Share an asset**

Generate a public share URL for an asset. If a share token already exists, returns the existing URL.

  Path Parameters:
    - id: string (required) — Asset UUID.

  Response (200): Share URL and token.
  ```json
  {
    "shareUrl": "https://tools.blueprintstudio.ai/s/abc123",
    "token": "abc123"
  }
  ```

### POST /api/v1/assets/:id/remove-bg

**Remove background**

Remove the background from an asset image and save the result as a new asset. Processing may take up to 60 seconds.

  Path Parameters:
    - id: string (required) — Source asset UUID.

  Note: This operation can take up to 60 seconds. The result is saved as a new asset linked to the original.

  Response (200): New asset with transparent background.
  ```json
  {
    "imageUrl": "https://...",
    "assetId": "uuid"
  }
  ```

## Styles

Manage visual styles — list, create, update, delete custom styles, analyze images for style extraction, and manage reference images.

### GET /api/v1/styles

**List styles**

List available styles including system defaults and user/brand custom styles.

  Response (200): Array of styles with full details.
  ```json
  {
    "styles": [{
      "id": "uuid",
      "name": "Minimalist",
      "description": "Clean, minimal design",
      "stylePrompt": "...",
      "colorPalette": [{ "hex": "#000", "name": "Black", "role": "primary" }],
      "styleDescriptors": ["clean", "modern"],
      "mood": "professional",
      "isSystem": true,
      "isDefault": false,
      "brandId": null,
      "createdAt": "2025-01-01T00:00:00Z"
    }]
  }
  ```

### GET /api/v1/styles/:id

**Get a style**

Get a single style by ID with all details.

  Path Parameters:
    - id: string (required) — Style UUID.

  Response (200): Full style details.
  ```json
  {
    "id": "uuid",
    "name": "Minimalist",
    "description": "Clean, minimal design",
    "stylePrompt": "...",
    "colorPalette": [...],
    "styleDescriptors": ["clean", "modern"],
    "mood": "professional",
    "isSystem": true,
    "isDefault": false,
    "brandId": null,
    "createdAt": "2025-01-01T00:00:00Z"
  }
  ```

### POST /api/v1/styles

**Create a style**

Create a new custom style with an AI generation prompt, optional color palette, and reference images.

  Request Body:
    - name: string (required) — Style name.
    - stylePrompt: string (required) — AI generation prompt for this style.
    - description: string — Human-readable description.
    - colorPalette: array — Array of { hex, name, role } color objects.
    - styleDescriptors: array — Array of descriptor strings (e.g., ["clean", "modern"]).
    - mood: string — Style mood (e.g., "playful", "professional").
    - brandId: string — Assign to a brand. Overrides API key's brandId.
    - referenceImages: array — Array of { data (base64), mimeType, filename } objects. Max 5.

  Response (201): Created style details.
  ```json
  {
    "id": "uuid",
    "name": "My Custom Style",
    "description": "...",
    "stylePrompt": "...",
    "colorPalette": [...],
    "styleDescriptors": [...],
    "mood": "playful",
    "brandId": null,
    "createdAt": "2025-01-01T00:00:00Z"
  }
  ```

### PUT /api/v1/styles/:id

**Update a style**

Update a custom style. System styles cannot be modified.

  Path Parameters:
    - id: string (required) — Style UUID.

  Request Body:
    - name: string — New name.
    - stylePrompt: string — New AI generation prompt.
    - description: string — New description.
    - colorPalette: array — New color palette.
    - styleDescriptors: array — Keywords describing the style.
    - mood: string — New mood.

  Response (200): Updated style details.
  ```json
  {
    "id": "uuid",
    "name": "Updated Style",
    "description": "...",
    "stylePrompt": "...",
    "colorPalette": [...],
    "mood": "bold",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
  ```

### DELETE /api/v1/styles/:id

**Delete a style**

Delete a custom style. System styles cannot be deleted.

  Path Parameters:
    - id: string (required) — Style UUID.

  Response (200): Deletion confirmation.
  ```json
  { "deleted": true }
  ```

### POST /api/v1/styles/analyze

**Analyze images for style**

Upload images to extract a style guide using AI vision. Returns colors, descriptors, typography analysis, mood, and a generated prompt.

  Request Body:
    - files: array (required) — Array of { data (base64), mimeType, filename } objects. Max 5 images.

  Rate Limit: Rate limited under styleAnalysis quota.

  Response (200): Extracted style analysis.
  ```json
  {
    "analysis": {
      "colors": ["#FF5733", "#333333"],
      "styleDescriptors": ["bold", "modern"],
      "typographyStyle": "sans-serif, clean",
      "mood": "energetic",
      "backgroundSuggestion": "white",
      "visualTechnique": "flat illustration",
      "generatedPrompt": "..."
    }
  }
  ```

### POST /api/v1/styles/:id/references

**Manage reference images**

Add or remove reference images from a custom style. System styles cannot be modified.

  Path Parameters:
    - id: string (required) — Style UUID.

  Request Body:
    - add: array — Array of { data (base64), mimeType, filename } objects to add. Max 5.
    - remove: array — Array of storage paths to remove.

  Response (200): Updated style with current reference files.
  ```json
  {
    "style": {
      "id": "uuid",
      "name": "My Style",
      "sourceFiles": [{ "storage_path": "...", "filename": "ref.png", "type": "image/png" }],
      "...": "..."
    }
  }
  ```

## Brands

Manage brands (organizations) — create, update, delete, manage settings, upload logos, and analyze websites for brand identity.

### GET /api/v1/brands

**List brands**

List all brands the authenticated user is a member of.

  Response (200): Array of brands with role and member count.
  ```json
  {
    "brands": [{
      "id": "uuid",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "role": "owner",
      "memberCount": 3,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }]
  }
  ```

### POST /api/v1/brands

**Create a brand**

Create a new brand. The authenticated user becomes the owner.

  Request Body:
    - name: string (required) — Brand name.

  Response (201): Created brand details.
  ```json
  {
    "brand": {
      "id": "uuid",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "role": "owner",
      "createdAt": "2025-01-01T00:00:00Z"
    }
  }
  ```

### GET /api/v1/brands/:id

**Get a brand**

Get a single brand with optional member list and settings includes.

  Path Parameters:
    - id: string (required) — Brand UUID.

  Query Parameters:
    - members: string (enum: true) — Set to "true" to include member list.
    - settings: string (enum: true) — Set to "true" to include brand settings.

  Response (200): Brand details with optional members and settings.
  ```json
  {
    "brand": {
      "id": "uuid",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "role": "owner",
      "permissions": ["write"],
      "createdAt": "2025-01-01T00:00:00Z",
      "members": [{ "id": "uuid", "userId": "uuid", "role": "owner", "joinedAt": "...", "user": { "email": "...", "display_name": "..." } }],
      "settings": { "defaultStyleId": "uuid", "promptTemplate": "..." }
    }
  }
  ```

### PUT /api/v1/brands/:id

**Update a brand**

Update a brand's name. Requires admin or owner role.

  Path Parameters:
    - id: string (required) — Brand UUID.

  Request Body:
    - name: string — New brand name.

  Response (200): Updated brand details.
  ```json
  {
    "brand": {
      "id": "uuid",
      "name": "New Name",
      "slug": "acme-corp",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  }
  ```

### DELETE /api/v1/brands/:id

**Delete a brand**

Permanently delete a brand. Only the owner can delete.

  Path Parameters:
    - id: string (required) — Brand UUID.

  Response (200): Deletion confirmation.
  ```json
  { "deleted": true }
  ```

### GET /api/v1/brands/:id/settings

**Get brand settings**

Get a brand's default style and prompt template settings.

  Path Parameters:
    - id: string (required) — Brand UUID.

  Response (200): Brand settings.
  ```json
  {
    "settings": {
      "defaultStyleId": "uuid",
      "promptTemplate": "Create a {prompt} in our brand style",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  }
  ```

### PUT /api/v1/brands/:id/settings

**Update brand settings**

Update a brand's default style and prompt template. Requires admin or owner role.

  Path Parameters:
    - id: string (required) — Brand UUID.

  Request Body:
    - defaultStyleId: string (nullable) — Default style ID for generation, or null to clear.
    - promptTemplate: string (nullable) — Prompt template with {prompt} placeholder, or null to clear.

  Response (200): Updated brand settings.
  ```json
  {
    "settings": {
      "defaultStyleId": "uuid",
      "promptTemplate": "Create a {prompt} in our brand style",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  }
  ```

### PUT /api/v1/brands/:id/logo

**Upload brand logo**

Upload or replace a brand's logo image. Requires admin or owner role.

  Path Parameters:
    - id: string (required) — Brand UUID.

  Request Body:
    - data: string (required) — Base64-encoded image data.
    - mimeType: string (required) — Image MIME type (e.g., "image/png").

  Response (200): Public logo URL (no expiry).
  ```json
  { "logoUrl": "https://..." }
  ```

### POST /api/v1/brands/analyze

**Analyze brand website**

Analyze a website to extract brand visual identity using an AI agent. Returns an NDJSON stream with status updates, insights, and a final style guide with 1–3 recommended styles.

  Request Body:
    - url: string (required) — Website URL to analyze.

  Note: Response is streamed as application/x-ndjson. Each line is a JSON object. Processing may take up to 50 seconds.

  Rate Limit: Rate limited under styleAnalysis quota.

  Response (200): NDJSON stream of events: { type: "status" | "insight" | "result" | "error", ... }
  ```json
  {"type":"status","message":"Starting brand analysis..."}
  {"type":"status","message":"Extracting color palette..."}
  {"type":"result","styles":[{"id":"style-1","name":"Brand Style","stylePrompt":"...","colors":["#FF5733"]}],"orgType":"saas","brandName":"Acme"}
  ```

### PATCH /api/v1/brands/:id/members/:userId

**Update member role**

Update a team member's role in the brand.

  Path Parameters:
    - id: string (required) — Brand UUID.
    - userId: string (required) — Member user ID.

  Request Body:
    - role: string (required, enum: admin | member) — New role for the member.

  Response (200): Updated member details.
  ```json
  {
    "member": {
      "userId": "uuid",
      "role": "admin",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  }
  ```

### DELETE /api/v1/brands/:id/members/:userId

**Remove a member**

Remove a team member from the brand.

  Path Parameters:
    - id: string (required) — Brand UUID.
    - userId: string (required) — Member user ID.

  Response (200): Removal confirmation.
  ```json
  { "removed": true }
  ```

### POST /api/v1/brands/:id/members/invite

**Invite a member**

Invite a new member to the brand by email.

  Path Parameters:
    - id: string (required) — Brand UUID.

  Request Body:
    - email: string (required) — Email address of the person to invite.
    - role: string (default: member, enum: admin | member) — Role to assign the invited member.

  Response (200): Invite details including the invite URL.
  ```json
  {
    "invite": {
      "id": "uuid",
      "email": "user@example.com",
      "role": "member",
      "inviteUrl": "https://tools.blueprintstudio.ai/invite/abc123",
      "expiresAt": "2025-01-08T00:00:00Z"
    }
  }
  ```

## Auth

Register a new account. No authentication required.

### POST /api/v1/auth/register

**Create an account**

Public endpoint — no authentication required. Creates a new user account and returns an API key in a single request. Intended for AI agents to self-serve access.

  Request Body:
    - email: string (required) — Email address for the new account.

  Note: No auth required. Returns 409 if the email is already registered. The API key is only shown once — store it securely.

  Response (201): Account created with an API key (shown only once).
  ```json
  {
    "apiKey": "bp_live_abc123...",
    "prefix": "bp_live_abc...",
    "userId": "uuid",
    "tier": "free",
    "message": "Account created. Save this API key — it will not be shown again."
  }
  ```

## API Keys

Manage API keys — list active keys, create new ones, and revoke existing keys.

### GET /api/v1/api-keys

**List API keys**

List all active (non-revoked) API keys for the authenticated user.

  Response (200): Array of API key metadata (keys are never returned after creation).
  ```json
  {
    "keys": [{
      "id": "uuid",
      "name": "Production",
      "prefix": "bp_live_abc",
      "tier": "pro",
      "lastUsedAt": "2025-01-01T00:00:00Z",
      "requestsToday": 42,
      "createdAt": "2025-01-01T00:00:00Z",
      "expiresAt": null,
      "brandId": null
    }]
  }
  ```

### POST /api/v1/api-keys

**Create an API key**

Create a new API key. Accepts either a Bearer token or session cookie auth (for logged-in users bootstrapping their first key). The full key is only returned once — save it immediately.

  Request Body:
    - name: string (default: Default) — Key name for identification.
    - brandId: string — Associate the key with a brand.

  Note: The full key value is only returned in this response. Store it securely. This endpoint also accepts session cookie auth — no existing API key needed if the user is logged in.

  Response (201): Full API key (shown only once) with metadata.
  ```json
  {
    "key": "bp_live_abc123...",
    "prefix": "bp_live_abc",
    "name": "Production",
    "tier": "pro",
    "message": "Save this key — it will not be shown again."
  }
  ```

### DELETE /api/v1/api-keys/:id

**Revoke an API key**

Revoke an API key. You cannot revoke the key currently being used for authentication.

  Path Parameters:
    - id: string (required) — API key UUID.

  Response (200): Revocation confirmation.
  ```json
  { "revoked": true }
  ```

## Settings

Get and update user-level settings like default style and prompt template.

### GET /api/v1/settings

**Get user settings**

Get the authenticated user's default style and prompt template settings.

  Response (200): User settings.
  ```json
  {
    "settings": {
      "defaultStyleId": "uuid",
      "promptTemplate": null
    }
  }
  ```

### PUT /api/v1/settings

**Update user settings**

Update the authenticated user's default style and prompt template.

  Request Body:
    - defaultStyleId: string (nullable) — Default style ID, or null to clear.
    - promptTemplate: string (nullable) — Prompt template with {prompt} placeholder, or null to clear.

  Response (200): Updated settings.
  ```json
  {
    "settings": {
      "defaultStyleId": "uuid",
      "promptTemplate": "Create a {prompt} in minimalist style"
    }
  }
  ```

## Usage

Check current usage, rate limits, and remaining quotas.

### GET /api/v1/usage

**Get usage & limits**

Get current usage statistics including generation counts, API request counts, and remaining quotas for the current billing period.

  Response (200): Current usage and limits.
  ```json
  {
    "tier": "pro",
    "generationsUsed": 150,
    "generationsLimit": 1000,
    "generationsRemaining": 850,
    "apiRequestsToday": 42,
    "apiRequestsLimit": 5000
  }
  ```