# List your API on DashAPI Connect

You are a coding agent working for an API vendor. Add the vendor's API to DashAPI Connect as one or
more operations, and submit it as a pull request. Do the work yourself. Ask the human only for what
you cannot find: their answers are short, so keep questions few and batched. `AGENTS.md` in the
Connect repo is authoritative: if it conflicts with this guide, follow `AGENTS.md` and say so in the PR.

Agents and backends call typed operations (for example `web.search`). Connect routes each call to a
ranked list of providers, falls back when one fails, and charges a fixed price per call.

## The flow

1. **Preflight.** Check the tools, then fork and clone the repo (commands below).
2. **Discover.** Ask the human for one thing: the vendor's API docs URL (and the OpenAPI spec URL if
   there is one). Read the docs, the pricing page and the spec yourself. Draft the endpoint list,
   prices, limits and auth from them.
3. **Confirm once.** Show the human one table: endpoint, proposed operation id, price, bulk price
   (or "none"), limit, returns personal data (yes or no). Ask only about what the docs did not answer
   (see "Ask the human"). Get a yes or edits. Do not ask
   one question at a time.
4. **Build.** Write definitions, adapter, bindings and tests.
5. **Verify.** Run tests and the live checks with the human's test key.
6. **Submit.** Branch, commit, push, open the PR (commands below), and give the human the PR link.

## Preflight

Run these. Fix what you can, ask for the rest.

```sh
git --version && go version && gh auth status
```

- No `gh`, or not logged in: tell the human to run `gh auth login`, then continue.
- Fork and clone, then work inside the clone:

```sh
gh repo fork DashAPI-ai/dashapi-connect --clone --default-branch-only
cd dashapi-connect
git checkout -b add-<vendor>-provider     # never work on main
```

- If the fork already exists, `gh repo fork` reuses it. Run `git pull --rebase upstream main` or
  `git fetch upstream && git rebase upstream/main` before you branch.
- Commits must be signed. Check: `git config --get commit.gpgsign` and `git config --get user.signingkey`
  (SSH signing also needs `gpg.format ssh`). If signing is not set up, stop and give the human
  GitHub's guide: https://docs.github.com/authentication/managing-commit-signature-verification.
  Never turn signing off, and never use `--no-gpg-sign`.
- Work only on the dedicated branch you create below. Never commit or push to `main`.
- Run `go test ./...` once now. If the baseline is already red, tell the human and stop.
- Put the test key in an environment variable for this session only. Never write it to a file in the repo.

## Eligibility (check while you discover)

Stop and tell the human if any of these is false. Do not work around it.

1. Access is self-serve: a person can get an API key without a sales call.
2. The key travels in a header (preferred) or a query parameter, and one cheap endpoint rejects an invalid key.
3. There is a public pricing page that says what each call costs.
4. The docs give example values for every input you will use.
5. The vendor allows a reseller or aggregator to call the API on behalf of other customers. Ask for
   the terms URL and put it in the PR.

## Ask the human

Take what you can from the docs first. Batch whatever is left into one message, then record the answers in the PR description. Do not guess.

1. Which of the endpoints you found should become operations?
2. What does a call cost the buyer, in USD, and what does it cost the vendor?
3. Is there a different price for bulk or batch processing? Volume tiers, a batch endpoint, an async
   bulk job and committed-spend discounts all count. If yes, get the thresholds, the price at each
   tier, and whether the bulk route is a separate endpoint or the same one at a lower rate. Check the
   pricing page first. Ask only if it is unclear. If there is none, record "none".
4. Rate and concurrency limits for Connect's traffic.
5. A sandbox or low-limit key for tests. It stays in your environment and never enters the repo.
6. Is the data public, or tied to the caller's own account? (This sets `data` and the credential mode.)
7. Does any listed operation return personal data? If yes, ask the nine questions in "Personal data
   and privacy" below, once for the whole listing, and skip any the vendor's documents already answer.
8. A contact email so Connect maintainers can arrange a test credential.

## Read the repo

- `AGENTS.md`: repo rules.
- `internal/capabilities/definitions/`: existing operation definitions (JSON). Copy the nearest one.
- `internal/providers/`: one directory per provider adapter (`hunter`, `zerobounce`, `semrush`...). Copy the nearest.
- `internal/providers/catalog/bindings.json`: which providers serve which operation, in rank order.
- `docs/PROVIDER_ADMISSION.md`: per-provider concurrency and per-minute limits.

## What the pull request contains

1. **Operation definitions** in `internal/capabilities/definitions/`.
2. **A provider adapter** in `internal/providers/<vendor>/`, with fixture tests.
3. **Bindings** in `internal/providers/catalog/bindings.json`.
4. **Admission limits** for the provider in `docs/PROVIDER_ADMISSION.md`.

Nothing else. No unrelated refactors, no formatting sweeps.

## Choose the operations

Reuse before you create.

- If an operation already does the job (`web.search`, `person.profile.find`...), add the vendor as a
  binding on it. Do not create a near-duplicate under a new id.
- Create a new operation only when nothing fits. Name the endpoint that needs it in the PR.
- An operation id is lowercase and dot separated: `domain.object.verb`.
- Prefer operations other providers can also serve. Shared operations are what routing and fallback need.

Curate the whole surface, not a sample:

1. List every documented endpoint.
2. Mark each one `listed` or `excluded`, with a one line reason (write endpoint, deprecated, needs
   account state, no stable schema...).
3. Include free count or preview routes, and the cheapest tier of each operation.
4. Aim for the endpoints buyers actually call, usually 5 to 15. Fewer is fine. Padding is not.

## Define each operation

- `id`, `version: 1`, `effect`: `read` unless the endpoint changes state. Writes and spend actions need
  human approval, are reviewed separately, and the PR must say so.
- `data` and `credential_modes`: `managed` for vendor-held access. Add `customer` only if buyers bring their own key.
- `input_schema`, `output_schema`: JSON Schema with `additionalProperties: false`, every string
  bounded by `maxLength`, every array by `maxItems`. No free-form objects.
- A fixed price in micro-USD (1 USD = 1,000,000). It does not vary per call. If the vendor's cost varies,
  price at the worst case and explain.
- Bulk pricing: if the vendor has a batch or bulk endpoint, list it as its own operation with its own price,
  not as a discount on the single-call one. Volume tiers on the same endpoint are not modeled by a fixed
  price: record the tiers in the PR and price at the standard rate. Maintainers decide how to pass tiers on.

Output is the same shape whichever provider answers. Map the vendor's field names onto the operation's
schema. Never pass raw vendor responses through.

## Write the adapter

Adapters are written in Go, like the rest of the repo. Copy the nearest existing one.

- Read the API key from configuration, never from code. Register the setting where other providers do.
- Use the shared client in `internal/httpx`. Set timeouts. Never log keys or full bodies.
- Return the correct outcome per case, because it decides routing and billing:
  - no result: `no_match` (Connect tries the next provider, buyer is not charged)
  - rate limited or 5xx: retryable (Connect falls back)
  - bad input or auth failure: permanent (no fallback, not charged)
- Add the provider to `bindings.json` for each operation with the rank the human agrees to.
- Add the provider's concurrency and per-minute limits to `docs/PROVIDER_ADMISSION.md`, citing the vendor's page.

## Verify yourself

Do these before you open the PR.

1. Tests run on recorded fixtures only: no live network calls in `go test`. Cover success, no match,
   rate limit, timeout, malformed vendor response, auth failure.
2. With the human's test key, call every listed endpoint once, live, with the example inputs. Record
   date, HTTP status and the charge the vendor metered. Reconcile each against the price you claimed.
3. Call the probe endpoint with a bad key and record the status and body.
4. Run `go test ./...` and the checks in the `Makefile`. Rebase on `main`.

If you cannot do step 2 or 3, say which and why. Do not fill in a number you did not observe.

## Personal data and privacy (GDPR and similar laws)

Many operations return personal data: names, emails, phone numbers, profiles. Buyers in the EU, UK,
Switzerland, California, Brazil and elsewhere need to know where it came from and what rules apply.
Do not guess any of this. Take it from the vendor's own documents or ask the human. "Unknown" is an
acceptable answer. An invented answer is not.

For every operation, state in the PR whether it returns personal data, and which categories
(name, work email, personal email, phone, location, employment history, social profile, other).
If the operation definition format has a field for this, set it. If it does not, put it in the PR and
say that the format needs one.

For a vendor that returns personal data, collect these once, for the whole listing:

1. **Source.** Where the data comes from (public sources, user-contributed, licensed, scraped, first party).
2. **Lawful basis.** The basis the vendor relies on (for example legitimate interest or consent), and if
   it is consent, who collects it and how it is recorded.
3. **Role.** Whether the vendor acts as controller or processor for the data it returns.
4. **DPA.** Whether the vendor offers a data processing agreement, and the URL of its terms.
5. **Sub-processors.** The URL of the vendor's sub-processor list.
6. **Location and transfers.** Where the data is stored and processed, and the transfer mechanism for
   data leaving the EU or UK (for example SCCs or the EU-US Data Privacy Framework).
7. **Retention.** How long the vendor keeps request data and returned data.
8. **Rights requests.** How a person can opt out, access or delete their record, and whether the vendor
   publishes a suppression or opt-out list or endpoint that Connect can honor.
9. **Regional limits.** Any region where the vendor does not allow, or does not support, use of the data.

Rules:

- A listing that returns personal data is incomplete without answers to 1 to 5. Mark the rest
  `unknown` if the vendor does not say.
- Do not claim compliance for the vendor ("GDPR compliant"). Report what the vendor's documents state
  and link them.
- Do not add consent collection, geo-blocking or filtering code. Connect handles those controls
  centrally, and maintainers decide how a listing is restricted by region.
- Never include personal data from real people in fixtures, tests or the PR. Use synthetic values.

## Rules

- Never put a credential value in the diff, fixtures, tests, PR description or commit messages.
- Do not mark an operation verified or commit real vendor response bodies. Maintainers do that after
  their own live check. Fixtures use synthetic values.
- Do not invent prices, limits or field names. If the docs are silent, ask or leave it out.
- Do not merge your own PR. Every commit in it must be signed.

## Submit

Write the PR body to a file first (`pr-body.md`, outside the repo tree or deleted afterwards). It must contain:

- the human's answers, and the contact email
- the full surface map: every documented endpoint, `listed` or `excluded`, with the reason
- a ledger per listed endpoint: date, HTTP status, claimed price, metered cost
- bulk and volume pricing: the tiers, thresholds and any batch endpoint, or "none"
- the probe's bad-key status and body
- the vendor's pricing URL, billing model, and terms URL for resellers
- the personal data declaration: per operation, whether it returns personal data and which categories, and the answers to the nine questions above
- test results, and anything you could not verify

Then:

```sh
git branch --show-current       # must be add-<vendor>-provider, not main
git add -A && git status        # read it: no keys, no stray files
git commit -S -m "Add <vendor> provider: <operation ids>"
git log --show-signature -1     # confirm the commit is signed
git push -u origin HEAD         # pushes the branch, never main
gh pr create --repo DashAPI-ai/dashapi-connect \
  --title "Add <vendor> provider: <operation ids>" \
  --body-file pr-body.md
```

Print the PR URL for the human. If a step fails, show the error and the fix. Do not force-push, skip hooks
or push to `main`. If the PR checks fail, read the log with `gh pr checks`, fix the cause and push again.

## What happens next

Connect maintainers check schema, limits, failure handling and the personal data answers, then run the live checks with their own
credential. Operations that pass join the catalog and enter the routing ranking. Commercial terms for
listed vendors are agreed per listing: raise them in the PR or write to the contact on
https://dashapi.ai/connect/list-your-api-on-dashapi-connect.
