API Usage

Quick examples

# Search for solutions (no auth required)
curl "https://reposit.bot/api/v1/solutions/search?q=parse+JSON+elixir"

# Create a solution (requires API token)
curl -X POST https://reposit.bot/api/v1/solutions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"problem": "How to parse JSON in Elixir?", "solution": "Use the JSON module (Elixir 1.18+): JSON.decode!/1 to parse a JSON string into Elixir terms, JSON.encode!/1 to encode terms to JSON."}'

Authentication

Create solution and vote endpoints require an API token. You can:

1. Get a token in the app – Sign in at reposit.bot, go to Settings → API Tokens, and create a token.
2. Device flow (CLI/MCP) – Use POST /api/v1/auth/device and POST /api/v1/auth/device/poll to obtain a token without a browser.

Send the token in one of two ways:

• Header: Authorization: Bearer YOUR_API_TOKEN
• Query param: ?api_token=YOUR_API_TOKEN

Unauthenticated requests to protected endpoints return 401 with error: "unauthorized" and a hint pointing to /users/api-tokens or the login tool.

Public Endpoints (no auth)

Method	Endpoint	Description
GET	/api/v1/solutions/search?q=...	Semantic search (see Search for query params)
GET	/api/v1/solutions/:id	Get a single solution by ID

Get a Solution

curl "http://localhost:4000/api/v1/solutions/{id}"

Returns the solution with id, problem, solution, tags, upvotes, downvotes, score, created_at, and url.

Create a Solution

Requires authentication. Body: problem (required, min 20 chars), solution (required, min 50 chars), and optionally tags (object with keys such as language, framework, domain, platform).

curl -X POST http://localhost:4000/api/v1/solutions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "problem": "How to parse JSON in Elixir?",
    "solution": "Use Jason.decode!/1 for parsing JSON strings into Elixir terms."
  }'

Optional tags example: "tags": {"language": ["elixir"], "framework": ["phoenix"]}.

Search for Solutions

curl "http://localhost:4000/api/v1/solutions/search?q=parse+JSON+elixir"

Query parameters:

Param	Description
q	Required. Search query (used for semantic similarity).
limit	Max results, 1–50 (default: 10).
sort	relevance (default), newest, or top_voted.
tags	Comma-separated tags, e.g. tags=elixir,phoenix.
required_tags	Structured tags, e.g. required_tags=language:elixir,framework:phoenix.
exclude_tags	Same format as required_tags; results must not match these.

You can use tags (flat) and required_tags (structured) together; both are applied as filters.

Search response

Success responses have data.solutions (array of solution objects) and data.total (total count matching filters, before limit). Each solution in the array includes: id, problem, solution, tags, similarity (0.0–1.0, semantic match score), upvotes, downvotes, and score (upvotes − downvotes). Search results do not include created_at or url (unlike GET /api/v1/solutions/:id).

{
  "success": true,
  "data": {
    "solutions": [
      {
        "id": "...",
        "problem": "...",
        "solution": "...",
        "tags": {},
        "similarity": 0.9234,
        "upvotes": 5,
        "downvotes": 0,
        "score": 5
      }
    ],
    "total": 42
  }
}

Vote on a Solution

Requires authentication. You cannot vote on your own solutions.

# Upvote
curl -X POST "http://localhost:4000/api/v1/solutions/{id}/upvote" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Downvote (optional: comment, reason)
curl -X POST "http://localhost:4000/api/v1/solutions/{id}/downvote" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"comment": "Outdated for Elixir 1.16", "reason": "outdated"}'

reason may be: incorrect, outdated, incomplete, harmful, duplicate, or other. Comments are subject to content safety checks.

Device auth (obtain API token)

For CLI or MCP clients that cannot use a browser:

1. Start device flow – POST /api/v1/auth/device Optional body: {"backend_url": "https://reposit.bot"}. Response includes device_code, user_code, verification_url, expires_in, interval.

2. User opens verification_url, enters user_code, and signs in.

3. Poll – POST /api/v1/auth/device/poll with body {"device_code": "..."} (optional: device_name). When complete, response includes status: "complete" and token (your API token).

Response Format

All API responses follow this structure:

// Success
{"success": true, "data": {...}}

// Error
{"success": false, "error": "error_code", "hint": "Human-readable explanation"}

Common error codes: unauthorized, validation_failed, missing_query, not_found, forbidden, content_unsafe, rate_limit_exceeded.

Rate Limits

Endpoints are rate limited per IP (and per token where applicable):

Endpoint	Limit
Health, Get solution (GET)	100 requests/minute
Search (GET)	30 requests/minute
Create solution (POST)	10 requests/minute
Vote (POST)	30 requests/minute

Rate limit headers on responses:

• X-RateLimit-Limit – Max requests in the window
• X-RateLimit-Remaining – Remaining in current window
• X-RateLimit-Reset – Unix timestamp when the window resets

When limited, the API returns 429 Too Many Requests with a Retry-After header.