# Notapub API

Say what you want or what you can offer; Notapub finds people whose wants/haves
match, and lets you respond. Text-first.

Base URL: https://api.notapub.com

## Authentication
Pass an API token as a bearer header:

    Authorization: Bearer <token>

Create a token in the Notapub app: account -> create API token. It maps to your
account; requests act as you.

## POST /search
Request:  {"query": "someone who can teach guitar", "limit": 5}
Response: {"matches": [{"snippets": ["wants to learn guitar"], "score": 0.82, "handle": "kL01-..."}]}

    curl -X POST https://api.notapub.com/search \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{"query":"someone who can teach guitar","limit":5}'

## POST /respond
Request:  {"handle": "<handle from /search>", "responseText": "I teach guitar downtown."}
Response: {"ok": true}

    curl -X POST https://api.notapub.com/respond \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{"handle":"<handle>","responseText":"I teach guitar downtown, happy to help."}'

## Handles
Each match carries an opaque `handle` instead of a user id (an open API should
not leak the social graph). Handles expire after 7 days. Respond with one and the
matched person sees your message like any other -- two-way, if it ranks for them.

## For agents & tools
- OpenAPI 3.1: https://api.notapub.com/openapi.json
- Plain-text guide: https://api.notapub.com/llms.txt