# TopIndexer API

> TopIndexer gets web pages indexed by Google. You submit a URL, we trigger the
> crawl, and we verify whether the page actually lands in Google's index —
> auto-refunding any URL that isn't indexed within 7 days. This file is a
> machine-readable guide for AI agents and tools integrating the public REST API.

Base URL: `https://api.topindexer.com`
Auth: `Authorization: Bearer ti_live_…` (create a key in Dashboard → Settings → API keys)
Content type: `application/json`. All endpoints live under `/api/v1`.

## Specs

- [OpenAPI 3.1 spec](https://topindexer.com/openapi.yaml): import into any agent, SDK generator, Postman, or Insomnia
- [Postman collection](https://topindexer.com/topindexer.postman_collection.json): one-click import, set the `apiKey` variable
- [Human docs](https://topindexer.com/docs/api): full reference with examples

## Endpoints

### POST /api/v1/submit
Submit 1–50 http(s) URLs for indexing. Deducts one credit per accepted URL.
Non-http(s) URLs are dropped and reported in `ignoredInvalid`. Returns 202.

Request body:
```json
{ "urls": ["https://example.com/page-a", "https://example.com/page-b"] }
```
Response (202):
```json
{
  "submitted": 1,
  "ignoredInvalid": 0,
  "submissions": [
    { "id": "01J9…ULID", "url": "https://example.com/page-a", "status": "queued" }
  ]
}
```
Errors: `400 bad_request` (no valid URLs), `400 too_many` (>50 URLs),
`401 unauthorized`, `402 insufficient_credits` (includes `required` + `available`).

### GET /api/v1/submissions
List your team's submissions, newest first. Optional query params:
`status` (one of the statuses below) and `limit` (default 50, max 200).
Response (200): `{ "submissions": [ <submission>, … ] }`.

### GET /api/v1/me
Return the authenticated team and credit balance.
Response (200): `{ "team": { "id", "name", "creditBalance" }, "keyId" }`.

## Submission status lifecycle

`queued` → `processing` → `submitted` → `crawled` → `indexed`.
Terminal alternatives: `not_indexed` (auto-refunded after the 7-day guarantee),
`failed` (provider rejected the URL), `refunded`.

## Notes for agents

- A key is bound to one team and acts on that team's credit balance. There are no
  per-endpoint scopes.
- Credits are spent at submit time and refunded automatically if a URL isn't
  indexed within 7 days — so polling `GET /api/v1/submissions` is the way to track
  outcomes; there is no need to hold a request open.
- Index status is verified honestly via a Google `site:` check, never Search Console.
- The first URL on a new account is free.

## Example (curl)

```bash
curl -X POST https://api.topindexer.com/api/v1/submit \
  -H "Authorization: Bearer ti_live_…" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/page-a"]}'
```