API Reference

Backend API endpoints for plugin development.

Base URL

Production: https://api.my-desk.ai
Development: http://localhost:8000

Authentication

All requests require a session token passed as a cookie:

curl -X GET "https://api.my-desk.ai/api/plugins/my-plugin/data" \
  -H "Cookie: session_token=YOUR_TOKEN"

Plugin Data API

List Plugin Data

Retrieve all data for a plugin filtered by user.

GET /api/plugins/{plugin_id}/data

Parameters:

Name	Type	Description
plugin_id	string	Plugin identifier
data_type	string (optional)	Filter by data type
limit	integer (optional)	Max items to return (default: 50)
offset	integer (optional)	Pagination offset

Response:

{
  "items": [
    {
      "id": "uuid",
      "plugin_id": "my-plugin",
      "user_id": "user-uuid",
      "data_type": "item",
      "content": { "title": "Example" },
      "metadata": { "created_at": "2024-01-01T00:00:00Z" }
    }
  ],
  "total": 100,
  "has_more": true
}

Get Single Item

GET /api/plugins/{plugin_id}/data/{item_id}

Response:

{
  "id": "uuid",
  "plugin_id": "my-plugin",
  "user_id": "user-uuid",
  "data_type": "item",
  "content": { "title": "Example", "body": "..." },
  "metadata": { "created_at": "2024-01-01T00:00:00Z" }
}

Create Item

POST /api/plugins/{plugin_id}/data

Request Body:

{
  "data_type": "item",
  "content": {
    "title": "New Item",
    "body": "Content here"
  },
  "metadata": {
    "status": "active"
  }
}

Response: Returns the created item with generated id.

Update Item

PUT /api/plugins/{plugin_id}/data/{item_id}

Request Body:

{
  "content": {
    "title": "Updated Title"
  },
  "metadata": {
    "updated_at": "2024-01-02T00:00:00Z"
  }
}

Delete Item

DELETE /api/plugins/{plugin_id}/data/{item_id}

Response:

{
  "success": true
}

Plugin Handlers API

Call custom backend handlers defined in your plugin.

Call Handler

POST /api/plugins/{plugin_id}/call/{handler_name}

Request Body:

{
  "args": {
    "param1": "value1",
    "param2": "value2"
  }
}

Response: Depends on the handler implementation.

Example:

curl -X POST "https://api.my-desk.ai/api/plugins/notes/call/create_note" \
  -H "Content-Type: application/json" \
  -H "Cookie: session_token=YOUR_TOKEN" \
  -d '{"args": {"title": "My Note", "body": "Content"}}'

Search API

Search plugin data using semantic similarity.

Semantic Search

POST /api/plugins/{plugin_id}/search

Request Body:

{
  "query": "search terms",
  "data_type": "item",
  "limit": 10,
  "filters": {
    "status": "active"
  }
}

Response:

{
  "results": [
    {
      "item": { ... },
      "score": 0.95
    }
  ]
}

Widget API

Get data for dashboard widgets.

Get Widget Data

GET /api/plugins/{plugin_id}/widget

Response: Depends on plugin's get_widget_data handler.

Error Responses

All errors follow this format:

{
  "detail": "Error message",
  "code": "ERROR_CODE"
}

Common Error Codes:

Code	Status	Description
NOT_FOUND	404	Resource not found
UNAUTHORIZED	401	Not authenticated
FORBIDDEN	403	Not authorized for this resource
VALIDATION_ERROR	422	Invalid request data
INTERNAL_ERROR	500	Server error

Rate Limits

Endpoint	Limit
Read operations	100/minute
Write operations	30/minute
Search operations	20/minute

TypeScript Types

interface PluginData {
  id: string;
  plugin_id: string;
  user_id: string;
  data_type: string;
  content: Record<string, any>;
  metadata: Record<string, any>;
  created_at: string;
  updated_at?: string;
}

interface ListResponse<T> {
  items: T[];
  total: number;
  has_more: boolean;
}

interface SearchResult<T> {
  item: T;
  score: number;
}

OpenAPI Spec

Full OpenAPI specification available at:

https://api.my-desk.ai/openapi.json