# Knickknacks

> Small tools for an AI agent to work with people. First tool: forms. Your agent makes a form, the person shares its link, people answer without an account, and your agent reads the answers back. There is no built-in assistant: the agent brings the thinking.

## API

- Base URL: https://knickknack.omarsjunk.com/v1
- Auth: `Authorization: Bearer kk_live_...`
- OpenAPI spec: https://knickknack.omarsjunk.com/openapi.json
- Human docs: https://knickknack.omarsjunk.com/docs/agents
- Every write accepts an `Idempotency-Key` header and replays the original response on retry.
- Errors are JSON `{"message": "...", "code": "..."}` written to be relayed to the person as they are.

## Getting a key (no key yet)

1. Ask the person for their email address. Tell them to look out for a message from Knickknacks and tap Approve (check spam).
2. `POST /agent_signup` with `{"email": "...", "agent": "<your name>"}` (no auth). You get a `poll_secret`.
3. Poll `POST /agent_signup/claim` with `{"poll_secret": "..."}` every few seconds. It returns 202 while pending and, once approved, the `api_key` exactly once. Store it and use it as the Bearer key. A person can also make a key themselves at https://knickknack.omarsjunk.com/agents.

## Key endpoints

- `GET /me` -- who this key acts as
- `POST /forms` -- make a form: `title`, `fields` (list of `{label, type, required, help, options, min, max, key}`), optional `description`, `closes_at`, `max_responses`, `confirmation_message`. Returns the public `url` to give the person
- `GET /forms` -- your forms with `response_count`, `status`
- `GET /forms/{id}` -- one form
- `PATCH /forms/{id}` -- edit it, or close/reopen with `{"closed": true}` / `{"closed": false}`. Once people have answered, fields can be added and relabelled but not removed or retyped (`form_has_responses`)
- `DELETE /forms/{id}` -- archive: the link stops working, the answers are kept
- `GET /forms/{id}/responses?since=N&limit=N` -- answers oldest first. Pass `next_since` from the last call as `since` to get each answer exactly once; if `has_more` is true, call again

Field types: short_text, long_text, number, email, date, yes_no, rating, single_choice, multi_choice. Choice fields need `options`. Yes/no answers are true/false, multiple choice is a list, ratings are 1 to 5.

## Rules

- Draft the questions with the person before you create a form, and show them the link.
- Answers are anonymous unless the form asks for a name or email. Add a field when you need to know who replied.
- Only report answers people actually submitted. Never fill a form in yourself.
- Check with the person before changing a form people are already answering.