llink/go/docs/api.md

API Documentation

All protected endpoints require a Bearer token in the Authorization header.

Authentication

Request Sign-In Code

POST /auth/request-code

Sends a 4-digit sign-in code to the provided email. Creates user if not exists.

Request Body:

{
  "email": "user@example.com"
}

Response: 204 No Content

Sign In

POST /auth/sign-in

Verifies the code and returns a session token.

Request Body:

{
  "email": "user@example.com",
  "code": "1234"
}

Response:

{
  "human": { "id": "...", "email": "...", "email_prefix": "...", "created_at": "..." },
  "token": "session_token"
}

Sign Out

POST /auth/sign-out (Protected)

Invalidates the current session. Returns 204 No Content.

Get Current User

GET /auth/me (Protected)

Returns the authenticated user.

---

Networks

Create Network

POST /networks (Protected)

Request Body:

{
  "name": "My Network"
}

List Networks

GET /networks (Protected)

Returns all networks the user is a member of.

Get Network

GET /networks/{id} (Protected)

Returns a specific network by ID.

Add Members to Network

POST /networks/{id}/members (Protected)

Request Body:

{
  "email_addresses": ["user1@example.com", "user2@example.com"]
}

Remove Member from Network

DELETE /networks/{id}/members/{email} (Protected)

Removes a member by email from the network.

---

Download Particle Object

GET /particles/{id}/download (Protected)

For now, the {id} should be an object id. Not the particle id.

Returns a 302 redirect to a signed download URL. Only works for media and file particles.

---

Depot (File Storage)

Prepare Upload

POST /depot/upload (Protected)

Prepares a signed URL for direct upload to GCS.

Request Body:

{
  "network_id": "network_uuid",
  "name": "filename.png",
  "content_type": "image/png",
  "content_length": 12345
}

Response:

{
  "object_id": "uuid",
  "upload_url": "https://storage.googleapis.com/...",
  "upload_headers": { "Content-Type": "image/png" }
}

Confirm Upload

POST /depot/objects/{id}/confirm (Protected)

Confirms that an upload has been completed.

Response:

{
  "id": "uuid",
  "name": "filename.png",
  "content_type": "image/png",
  "content_length": 12345,
  "contains_content": true,
  "created_at": "..."
}

Upload Flow

1. POST /depot/upload — get signed URL and object_id
2. Upload file directly to GCS using the signed URL
3. POST /depot/objects/{id}/confirm — mark upload complete
4. Create a media or file particle with the object_id in its data

---

Object Reference

Human

Field	Type	Description
id	string | null	Unique identifier. Null if not yet registered.
email	string	Email address (stable identifier).
email_prefix	string	The local part of the email (before @).
created_at	string | null	ISO 8601 timestamp. Null if not registered.

{
  "id": "abc-123",
  "email": "alice@example.com",
  "email_prefix": "alice",
  "created_at": "2025-01-15T10:30:00Z"
}

Network

Field	Type	Description
id	string	Unique identifier.
name	string	Display name of the network.
admin_human	Human	The network administrator.
humans	Human[]	All members of the network (including admin).
created_at	string	ISO 8601 timestamp.

{
  "id": "net-456",
  "name": "My Team",
  "admin_human": { "id": "abc-123", "email": "alice@example.com", "email_prefix": "alice", "created_at": "..." },
  "humans": [
    { "id": "abc-123", "email": "alice@example.com", "email_prefix": "alice", "created_at": "..." }
  ],
  "created_at": "2025-01-15T10:30:00Z"
}

DepotObject

Returned by POST /depot/objects/{id}/confirm.

Field	Type	Description
id	string	Unique object identifier.
name	string	Original filename.
content_type	string	MIME type (e.g. image/png).
content_length	integer	Size in bytes.
contains_content	boolean	Whether the object has been uploaded successfully.
created_at	string	ISO 8601 timestamp.

---

Particle Data by Type

The data field on a Particle is a JSON object whose schema depends on the particle's type.

stream

Field	Type	Description
name	string	Stream name (required).
status	string	"open" or "closed" (required).
description	string | null	Stream description (optional).

{ "name": "Sprint Planning", "status": "open", "description": "Weekly sync" }

folder

Field	Type	Description
name	string	Folder name (required).
color	string | null	Display color (optional).

{ "name": "Design Assets", "color": "#FF5733" }

media

Field	Type	Description
object_id	string	Reference to depot storage object (required).
mime_type	string	MIME type of the media (required).
duration_ms	integer	Duration in milliseconds, must be > 0 (required).

{ "object_id": "obj-123", "mime_type": "image/jpeg", "duration_ms": 5000 }

file

Field	Type	Description
object_id	string	Reference to depot storage object (required).
filename	string	Original filename (required).
mime_type	string	MIME type (required).
size	integer	File size in bytes, must be > 0 (required).

{ "object_id": "obj-456", "filename": "report.pdf", "mime_type": "application/pdf", "size": 204800 }

text

Field	Type	Description
content	string	Text content (required).

{ "content": "Hello world" }

quest

Field	Type	Description
title	string	Quest/task title (required).
description	string	Details about the quest (required).
status	string | null	Current status (optional, e.g. "todo", "in_progress", "done").
assigned_to	string | null	Email of the assigned user (optional).
due_date	string | null	ISO date string (optional, e.g. "2025-03-01").

{ "title": "Fix login bug", "description": "Login fails on Safari", "status": "todo", "assigned_to": "bob@example.com" }

paper

Field	Type	Description
title	string	Document title (required).
content	string	Document body in markdown (required).

{ "title": "Architecture RFC", "content": "## Overview\n..." }

---

Error Responses

All endpoints return standard HTTP status codes with plain text error bodies:

• 400 Bad Request — invalid input or missing required fields
• 401 Unauthorized — missing or invalid auth token
• 403 Forbidden — user lacks permission (not a member, not creator, not admin)
• 404 Not Found — resource doesn't exist
• 409 Conflict — state conflict (stream already open/closed, capacity exceeded)
• 500 Internal Server Error