# Sloppybee API - Complete Documentation for AI Agents

> This is the detailed API documentation for AI assistants and LLM agents integrating with Sloppybee.

## Overview

Sloppybee provides a REST API for creating and managing shareable task lists. Perfect for:
- Todo lists
- Shopping lists
- Checklists
- Packing lists
- Project task breakdowns
- Any organized list of items

## Base URL

```
https://jividmjmugtygaqtigml.supabase.co/functions/v1
```

## Authentication

All API requests require a Bearer token in the Authorization header:

```
Authorization: Bearer sb_live_YOUR_API_KEY
```

Get your API key at: https://sloppybee.com/developers

### Zero-Touch Agent Registration (no email, no captcha)

Autonomous AI agents can self-provision a key:

```
POST https://jividmjmugtygaqtigml.supabase.co/functions/v1/agent-register
Content-Type: application/json

{
  "agent_name": "MyAgent",
  "agent_url": "https://my-agent.example.com",
  "contact_email": "optional@example.com"
}
```

Response includes `api_key` (prefix `sb_agent_`), `rate_limit_per_hour: 20`, `expires_in_days: 7`. Per-IP cap: 3 registrations/hour. Use the returned key the same way as a human key (`Authorization: Bearer sb_agent_...`). For higher limits or non-expiring keys, use the human flow at https://sloppybee.com/api.

## Agent Handshake (One-Call Discovery)

New foreign agents can hit a single endpoint to retrieve the entire API surface (endpoints, auth, rate limits, example payloads, tool definition links) without scraping docs:

```
GET https://jividmjmugtygaqtigml.supabase.co/functions/v1/agent-handshake
```

Returns capabilities, endpoint catalog, auth flow, rate limits, links to all framework tool definitions (OpenAI, Anthropic, Google, LangChain, Vercel AI SDK, Mistral), MCP server, OpenAPI spec, and policy URLs. Cacheable for 5 minutes.

## next_actions Field

All v1 success responses include a `next_actions` array. Each entry has `{ action, endpoint, method, description, requires_auth, example_body }`. Agents should prefer following `next_actions` over building URLs from memory.

---

## Endpoints

### 1. Create a Task List

**POST** `/api-v1-lists-create`

Creates a new shareable task list and returns a unique URL.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| title | string | No | List title (default: "Untitled List") |
| tasks | array | No* | Array of task objects |
| ai_generate | boolean | No | Generate tasks with AI |
| ai_prompt | string | No* | Description for AI generation |
| ai_count | number | No | Number of AI tasks (default: 5) |
| expires_in_days | number | No | Days until expiration (1-30, default: 7) |

*Either `tasks` or `ai_generate` with `ai_prompt` is required.

#### Task Object

```json
{
  "task": "Task description",
  "done": false
}
```

#### Example: Manual Task Creation

```bash
curl -X POST "https://jividmjmugtygaqtigml.supabase.co/functions/v1/api-v1-lists-create" \
  -H "Authorization: Bearer sb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Grocery Shopping",
    "tasks": [
      {"task": "Milk", "done": false},
      {"task": "Bread", "done": false},
      {"task": "Eggs", "done": false},
      {"task": "Butter", "done": false}
    ],
    "expires_in_days": 7
  }'
```

#### Example: AI-Generated Tasks

```bash
curl -X POST "https://jividmjmugtygaqtigml.supabase.co/functions/v1/api-v1-lists-create" \
  -H "Authorization: Bearer sb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Beach Vacation Packing",
    "ai_generate": true,
    "ai_prompt": "Essential items for a week-long beach vacation",
    "ai_count": 10
  }'
```

#### Success Response (200)

```json
{
  "success": true,
  "slug": "abc123",
  "url": "https://sloppybee.com/view/abc123",
  "title": "Beach Vacation Packing",
  "tasks": [
    {"id": "1", "task": "Sunscreen SPF 50+", "done": false},
    {"id": "2", "task": "Beach towels", "done": false}
  ],
  "expires_at": "2024-01-15T00:00:00.000Z"
}
```

---

### 2. Get a Task List

**POST** `/api-v1-lists-get`

Retrieves an existing task list by its slug.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| slug | string | Yes | The list identifier from the URL |
| password | string | No | Required if list is password-protected |

#### Example

```bash
curl -X POST "https://jividmjmugtygaqtigml.supabase.co/functions/v1/api-v1-lists-get" \
  -H "Authorization: Bearer sb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug": "abc123"}'
```

#### Success Response (200)

```json
{
  "success": true,
  "slug": "abc123",
  "title": "Grocery Shopping",
  "tasks": [
    {"id": "1", "task": "Milk", "done": true},
    {"id": "2", "task": "Bread", "done": false}
  ],
  "created_at": "2024-01-08T12:00:00.000Z",
  "expires_at": "2024-01-15T00:00:00.000Z",
  "is_protected": false
}
```

---

### 3. Generate Tasks (Without Creating List)

**POST** `/api-v1-tasks-generate`

Generates task suggestions using AI without creating a list. Useful for previewing or customizing before creation.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| prompt | string | Yes | Description of tasks to generate |
| count | number | No | Number of tasks (1-20, default: 5) |
| existing_tasks | array | No | Existing tasks to consider |

#### Example

```bash
curl -X POST "https://jividmjmugtygaqtigml.supabase.co/functions/v1/api-v1-tasks-generate" \
  -H "Authorization: Bearer sb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Things to do before a job interview",
    "count": 8
  }'
```

#### Success Response (200)

```json
{
  "success": true,
  "tasks": [
    {"task": "Research the company thoroughly", "done": false},
    {"task": "Prepare answers to common interview questions", "done": false},
    {"task": "Choose and prepare your outfit", "done": false}
  ]
}
```

---

## Error Responses

### 400 Bad Request

```json
{
  "error": "Invalid request",
  "message": "Either tasks array or ai_generate with ai_prompt is required"
}
```

### 401 Unauthorized

```json
{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}
```

### 429 Rate Limited

```json
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please wait before retrying."
}
```

---

## Rate Limits

- **100 requests per hour** per API key
- Rate limits reset hourly
- Usage is tracked and logged

---

## OpenAI Function Schema

For ChatGPT and other OpenAI-compatible systems, use this function definition:

```json
{
  "name": "create_sloppybee_list",
  "description": "Create a shareable task list on Sloppybee. Use when users want to create todos, shopping lists, checklists, or any organized list of tasks.",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Title of the task list"
      },
      "tasks": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "task": {"type": "string"},
            "done": {"type": "boolean", "default": false}
          },
          "required": ["task"]
        },
        "description": "Array of tasks to add"
      },
      "ai_generate": {
        "type": "boolean",
        "description": "Set to true to have AI generate tasks"
      },
      "ai_prompt": {
        "type": "string",
        "description": "Description for AI task generation"
      },
      "expires_in_days": {
        "type": "integer",
        "minimum": 1,
        "maximum": 30,
        "default": 7
      }
    }
  }
}
```

---

## Best Practices for AI Agents

1. **Always return the URL**: After creating a list, provide the user with the `url` from the response
2. **Use AI generation for complex requests**: When users describe a scenario, use `ai_generate` with a detailed `ai_prompt`
3. **Set appropriate expiration**: Use `expires_in_days` based on the task type (e.g., 1 day for daily tasks, 14 for projects)
4. **Handle errors gracefully**: Check for error responses and provide helpful feedback

---

## Integration Resources

- OpenAPI Specification: https://sloppybee.com/api/openapi.yaml
- OpenAI Plugin Manifest: https://sloppybee.com/.well-known/ai-plugin.json
- Tool Schema (JSON): https://sloppybee.com/api/openai-tools.json
- Developer Portal: https://sloppybee.com/developers

---

## Support

- Email: support@sloppybee.com
- Contact Form: https://sloppybee.com/contact
- Terms of Service: https://sloppybee.com/terms
- Privacy Policy: https://sloppybee.com/privacy