# BuildStore — Agent Guide

> BuildStore is a sideload-friendly iOS app store. This document describes how AI agents and automated clients should interact with the site.

## Operator

- **Entity:** Pixel Rainbow Inc. dba Builds.io
- **Address:** 700 North Fairfax Str. STE 614, Alexandria, Virginia 22314, USA
- **Support:** support@builds.io
- **Legal / privacy:** legal@builds.io
- **Partners:** partners@builds.io

## Public surfaces (safe to crawl)

- Landing — https://builds.io/
- App catalog — https://builds.io/apps/
- About — https://builds.io/about_us
- Help center — https://builds.io/help-center
- Knowledge base — https://builds.io/solutions
- Legal — https://builds.io/legal/terms, https://builds.io/legal/privacy-policy

## Restricted surfaces (do not crawl)

User-personalized and transactional flows. Authoritative list lives in [`robots.txt`](https://builds.io/robots.txt). Highlights:

- `/account*`, `/my-apps*`, `/my-partner-dashboard*`
- `/auth/*`, `/device/*`, `/admin*`, `/secret-signer`
- `/payment/*`, `/new-checkout*`
- `/api/*`, `/open-from-mobile`, `/redirect-to-app`

## Discovery files

- LLM-friendly site index: https://builds.io/llms.txt
- Sitemap: https://builds.io/sitemap.xml
- Agent metadata: https://builds.io/.well-known/agent.json
- API catalog (RFC 9727): https://builds.io/.well-known/api-catalog
- Agent skills index (v0.2.0): https://builds.io/.well-known/agent-skills/index.json
- Web Bot Auth directory: https://builds.io/.well-known/http-message-signatures-directory

## Authentication

**This API is NOT OAuth 2.0 or OpenID Connect.** It uses Django REST Framework's
SimpleJWT scheme with a JSON request body. There is intentionally no
`/.well-known/openid-configuration` or `/.well-known/oauth-authorization-server`
file — those would misrepresent the actual flow. A minimal RFC 9728 descriptor
is published at https://builds.io/.well-known/oauth-protected-resource (with
`authorization_servers: []` and the JWT-Bearer flow described under non-standard
`x_*` fields). Use the endpoints below.

| Step | Endpoint | Method | Body |
|---|---|---|---|
| Sign in | `https://ng-api.builds.io/api/v1/auth/token/` | POST | `{"email": "...", "password": "..."}` |
| Refresh access token | `https://ng-api.builds.io/api/v1/auth/token/refresh/` | POST | `{"refresh": "<refresh_jwt>"}` |
| Read current user | `https://ng-api.builds.io/api/v1/auth/current/` | GET | (none) |
| Authenticated calls | `https://ng-api.builds.io/api/v1/...` | any | (none) |

All requests use `Content-Type: application/json`. Authenticated endpoints
require `Authorization: Bearer <access_jwt>`.

### Sign in

```bash
curl -X POST 'https://ng-api.builds.io/api/v1/auth/token/' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","password":"<password>"}'
```

Successful response (200):

```json
{
  "access": "<access_jwt>",
  "refresh": "<refresh_jwt>",
  "user": { ... }
}
```

Failure shape (200 with `success:false`, or 400):

```json
{
  "success": false,
  "errors": {
    "__all__": ["No active account found with the given credentials"]
  }
}
```

### Refresh

```bash
curl -X POST 'https://ng-api.builds.io/api/v1/auth/token/refresh/' \
  -H 'Content-Type: application/json' \
  -d '{"refresh":"<refresh_jwt>"}'
```

Returns `{"access": "<new_access_jwt>"}`.

### Authenticated request

```bash
curl 'https://ng-api.builds.io/api/v1/auth/current/' \
  -H 'Authorization: Bearer <access_jwt>'
```

### Token lifetimes

Access tokens are short-lived; the frontend treats sessions as ~7 days and
refreshes proactively. Exact lifetimes are server-side configuration; if needed,
re-derive from the JWT `exp` claim.

### Why no OAuth metadata

OAuth 2.0 password grant requires `application/x-www-form-urlencoded` with
`grant_type=password&username=…`; this API expects `application/json` with
`{email, password}`. Publishing an RFC 8414 / OIDC discovery document would
direct agents to flows that 400-fail. Real OAuth 2.0 / OIDC support is not yet
implemented on the backend; until then, follow the JWT flow above.

## AI-usage policy

- **Indexing for retrieval / answer-grounding:** allowed for the public surfaces above.
- **Training on site content:** not granted by default. Contact legal@builds.io for licensing.
- **Rate:** keep request rate reasonable; honor `Crawl-delay` if added in the future.
- **Identification:** send a descriptive `User-Agent` and, where possible, a contact URL.

## Reporting issues

- Abuse / takedown: legal@builds.io
- Security: support@builds.io with subject `Security`