Developers

Have & Seek API (v1)

A JSON API for other apps and programs. Anyone can browse everything public without an account. A member can also let your app act for them, with their own sign-in, to post, upload photos, save, block, report and send messages. The machine-readable description is at /api/v1/openapi.json.

Using ChatGPT, Claude, Gemini or Perplexity? See Connect AI assistants for the MCP connector.

Basics

• Success: { "data": …, "meta": … } (meta on lists). Failure: { "error": { "code", "message", "details" } }.
• Money is always integer US cents (USD). Distances are whole miles. Times are ISO 8601.
• Public endpoints need no account and return only published or closed posts and public profiles of active members. Signing in does not change what they return.
• Member endpoints read and change only that member’s own data: their posts and drafts, photos, profile, saved posts, blocks and conversations. Other members’ private data is never returned. There are no admin or moderation operations, even for admin accounts.
• Cross-origin requests are allowed from any site without cookies. Responses are never cached and are not for search engines.
• Rate limits apply per server, so treat them as approximate: about 600 public reads per minute in total, 120 reads and 30 writes per member per minute, and 10 image uploads per member per minute. A 429 response says how long to wait in Retry-After. Posts, messages, reports and saves also have the same database limits as the website.

Endpoints

Signing in for member endpoints

Member endpoints take the member’s access token in Authorization: Bearer …. Cookies and tokens in the URL are ignored, and the API never creates accounts, sessions or tokens. Your app gets the member’s own session:

1. Read /api/v1/auth/config for the public Supabase connection settings, enabled methods and email return address. The publishable key identifies the project; it is not a member login.
2. In your app, use the Supabase Auth client library with those details and let the member sign in. Google sign-in only returns to your app after the operator adds your app’s exact return address to the project’s allowed list. Email codes work with any email provider when enabled; request them with the returned email_redirect_url, then use auth.verifyOtp in your app. A member who has set an optional password on the website (My account) can use it where password sign-in is enabled. If the project requires a security check (CAPTCHA) for sign-in, your app must pass one too.
3. The account must be an active member (a confirmed email address or Google). Otherwise the API answers 403 with not_member. New members can join through the website or the enabled Supabase Auth signup flow; email accounts must confirm their address first.
4. Send the session’s access token. It expires after about an hour; refresh it with the same library.

What a token allows. The access token is the member’s full session: whoever holds it can do everything listed under the member endpoints as that member, just like on the website. There are no per-app permissions, consent screens or per-app revocation yet. Signing out ends refresh access; an issued access token may remain valid until it expires. Account access revocation is checked on every member request. Treat tokens like passwords: never put them in URLs, logs, messages or shared code. Scoped permissions for third-party apps are a possible future addition, not something this API offers today.

Examples

Shell examples use Bash. Set the uppercase variables from the API responses before running a command.

# HS_API is the site origin, e.g. https://haveandseek.com. No account needed.
curl -s "$HS_API/api/v1/listings?kind=product&location_id=$LOCATION_ID&radius_miles=25&limit=10"
curl -s "$HS_API/api/v1/quests/$POST_ID"
curl -s "$HS_API/api/v1/listings/$POST_ID/photos"
curl -s "$HS_API/api/v1/members/$MEMBER_ID"
curl -s "$HS_API/api/v1/members/$MEMBER_ID/posts?limit=10"
curl -s "$HS_API/api/v1/posts/$POST_ID/map-candidates?w=-78.2&s=38.4&e=-76.6&n=39.3"
curl -s "$HS_API/api/v1/locations?q=Arlington,%20VA"

# HS_TOKEN is the access token of a member signed in through your app.
curl -s "$HS_API/api/v1/me" -H "Authorization: Bearer $HS_TOKEN"

curl -s -X POST "$HS_API/api/v1/posts" \
  -H "Authorization: Bearer $HS_TOKEN" -H "Content-Type: application/json" \
  -d @- <<JSON
  {
    "type": "listing", "kind": "product",
    "group_id": "$GROUP_ID", "subcategory_id": "$SUBCATEGORY_ID",
    "title": "Oak writing desk", "description": "Solid oak, 48 in wide, light wear.",
    "location_id": "$LOCATION_ID", "condition": "good",
    "price": { "mode": "fixed", "amount_cents": 12500, "negotiable": true },
    "status": "draft"
  }
JSON

# Add a photo: the body is the raw image file
curl -s -X POST "$HS_API/api/v1/posts/$POST_ID/photos" \
  -H "Authorization: Bearer $HS_TOKEN" -H "Content-Type: image/jpeg" \
  --data-binary @desk.jpg

# Publish, using the ETag you last received
curl -s -X POST "$HS_API/api/v1/posts/$POST_ID/status" \
  -H "Authorization: Bearer $HS_TOKEN" -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" -d '{ "status": "published" }'

# Or throw a draft away (drafts only; published posts are archived)
curl -s -X DELETE "$HS_API/api/v1/posts/$POST_ID" \
  -H "Authorization: Bearer $HS_TOKEN" -H "If-Match: $ETAG"

# Save a post and block a member (both idempotent)
curl -s -X PUT "$HS_API/api/v1/me/saved/$POST_ID" -H "Authorization: Bearer $HS_TOKEN"
curl -s -X PUT "$HS_API/api/v1/me/blocks/$MEMBER_ID" -H "Authorization: Bearer $HS_TOKEN"

# Ask about a post. Keep CLIENT_TOKEN unchanged when retrying this same message.
CLIENT_TOKEN="$(uuidgen)"
curl -s -X POST "$HS_API/api/v1/posts/$POST_ID/conversations" \
  -H "Authorization: Bearer $HS_TOKEN" -H "Content-Type: application/json" \
  -d @- <<JSON
  { "body": "Is the desk still available?", "client_token": "$CLIENT_TOKEN",
    "proposed_price": { "basis": "total", "amount_cents": 11000 } }
JSON

# Read new messages (keep the last next_cursor and poll with it), then mark read
curl -s "$HS_API/api/v1/conversations/$CONVERSATION_ID/messages?cursor=$CURSOR" -H "Authorization: Bearer $HS_TOKEN"
curl -s -X POST "$HS_API/api/v1/conversations/$CONVERSATION_ID/read" -H "Authorization: Bearer $HS_TOKEN"

Creating and editing posts

POST /api/v1/posts creates a post. PUT /api/v1/posts/{id} replaces every editable field (anything optional you leave out is cleared) and keeps the status. The same rules as the website apply: drafts still need type, kind, category, title, place and price; anything that is or was public must also meet the publishing rules. Unknown fields, and fields that do not apply (for example a condition on a service), are refused.

Author, status (on PUT), publication and moderation fields can never be set. DELETE /api/v1/posts/{id} permanently removes a draft (one that was never published) and needs its If-Match; published, paused and closed posts are never deleted, only archived.

Status changes and conflicts

• Draft → published or archived. Published → paused, closed or archived. Paused → published, closed or archived. Closed → published or archived. Archived is final.
• Closing needs closed_reason (sold, fulfilled, closed): product Listings can be sold or closed, service Listings closed, Quests fulfilled or closed.
• Every change needs the version you last read: expected_updated_at in the body or If-Match with the ETag header. If the post changed meanwhile you get 409 conflict; read it again and retry.

Photos and profile images

• Uploads send the raw image file as the request body (not a form, not base64) with Content-Type: image/jpeg, image/png or image/webp, up to 4 MB. The content must match the type.
• The server re-encodes every image to WebP and removes all metadata, including location. Post photos are at most 2000 px on the long side; profile images are cropped to 512 × 512. A post can have 6 photos.
• Image links stop working after about a minute. Request them again when you need them; do not store them. Your profile image is public on your member page and posts.
• If storing succeeds but the database then refuses the photo, the new file is removed again and the error says whether that worked (uploaded_file). Deletes report whether the stored file was removed (removed or cleanup_pending).

Messages

• POST /api/v1/posts/{id}/conversations sends the first message about a published post; replies go to POST /api/v1/conversations/{id}/messages. Messages are plain text up to 2000 characters, with an optional proposed price (basis total, hour, job, day, quote; an amount in cents unless the basis is quote).
• Every message needs a client_token: a new UUID you generate per message. If a request fails or times out, retry with the same token; the message is never sent twice.
• Only the two participants can read a conversation. Reading messages does not mark them read; call POST …/read when the member has seen them. The inbox shows the newest conversations (up to 50); older ones are not reachable through v1.
• Messages from your app are real messages to real people. Blocks, display-name and rate limits apply as on the website. Never send passwords, tokens or card details in a message.

Saved posts, blocks and reports

• PUT and DELETE on /api/v1/me/saved/{postId} and /api/v1/me/blocks/{memberId} can be repeated safely; the answer says whether anything changed.
• Reports (reasons: spam, scam, prohibited, offensive, harassment, other) go to the moderators and cannot be read back through the API.

Paging

Lists return up to limit items (default 20, maximum 50). meta.has_more is true only when another item exists; pass meta.next_cursor as cursor with the same filters for the next page. Cursors only work for the list, sort or conversation they came from. A member’s public posts and your inbox have no cursor: they show the newest items only (a member’s posts up to 49); use search for complete browsing.

Errors

Questions: see How it works.