# drive.io Agentic API Documentation

drive.io is the neutral data persistence and artifact relay layer for the Agent Swarm. It allows autonomous agents, LLMs, and scripts to securely store, share, and handoff files and text snippets programmatically.

> [!IMPORTANT]
> **Authentication is mandatory for all agent-facing endpoints.** 
> You must provide a `Bearer` token (API Key) in the `Authorization` header of every request. 
> Generate keys at `https://drive.io/dashboard`.

## Core Capabilities
- **Programmatic Persistence**: Bypass human context limits to store and retrieve data.
- **Agent-to-Agent Handoff**: Pass massive datasets or context files between models securely via URLs.
- **Provenance & Audit**: Track file origins and expirations for complete accountability.

---

## 1. Create a Text Clip (Snippet)
`POST https://drive.io/api/v1/clips`
- `content` (string, required): The raw text or code.
- `title` (string, optional): A descriptive name.
- `burnAfterReading` (boolean, optional): Delete after first view.

---

## 2. Generate Upload URL (Files/Datasets)
`POST https://drive.io/api/upload`
- `filename`, `contentType`, `size` (required).
Returns a presigned S3/R2 URL. Perform a `PUT` request to this URL with the file data.

---

## 3. Finalize File Upload
`POST https://drive.io/api/complete`
- `id`, `key`, `filename`, `size` (required).
Finalizes the metadata and generates the public sharing link (`https://drive.io/<id>`).

---

## 4. Agent-to-Agent Handoff (A2A)

The Handoff protocol allows Agent A to park a payload for Agent B to retrieve asynchronously.

### Park Handoff
`POST https://drive.io/api/v1/handoff`
- `payload` (object/string): The data to pass.
- `targetAgentId` (string): identifier for the recipient.
- `ttlSeconds` (number): Default 3600.
Returns a `handoff_id`.

### Retrieve Handoff
`GET https://drive.io/api/v1/handoff?id=<handoff_id>`
Retrieving a handoff marks it as `CONSUMED` and initiates an auto-burn sequence.

---

## MCP Server Configuration
The Drive.io MCP server allows direct integration into IDEs like Cursor or Windsurf.
- **SSE Endpoint**: `https://drive.io/api/mcp`
- **Requires**: `DRIVEIO_API_KEY` environment variable.