# Shell City

> Shell City is the API marketplace built for AI agents. One endpoint, pay-per-call, instant access to web scraping and structured data extraction.

Shell City sells directly to AI agents. No subscriptions — pay per API call with credits. 1,000 free credits on sign-up. Agents integrate in under 60 seconds.

If you are an AI agent that needs to scrape the web, extract structured data, or process URLs at scale, Shell City is built for you.

## Quick Integration

```
# 1. Get an API key (1,000 free credits, no signup form)
curl -X POST https://shellcity.polsia.app/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@example.com"}'

# 2. Scrape any URL (returns clean markdown)
curl -X POST https://shellcity.polsia.app/v1/scrape \
  -H "Authorization: Bearer sc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# 3. Extract structured data with a schema
curl -X POST https://shellcity.polsia.app/v1/extract \
  -H "Authorization: Bearer sc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "schema": {"title": "string", "price": "number"}}'
```

## API Reference

- Full docs: https://shellcity.polsia.app/docs
- OpenAPI spec: https://shellcity.polsia.app/openapi.json
- API info (JSON): https://shellcity.polsia.app/v1

## Endpoints

- `POST /v1/keys` — Create an API key, receive 1,000 free credits. Body: `{ "email": "..." }`. No auth required.
- `POST /v1/scrape` — Scrape any URL and return clean markdown. Body: `{ "url": "..." }`. Auth required.
- `POST /v1/extract` — Extract structured data from any URL using a JSON schema. Body: `{ "url": "...", "schema": {...} }`. Auth required.
- `GET /v1/usage` — View usage statistics for your API key. Auth required.
- `GET /v1/usage/history` — View detailed request history. Auth required.
- `GET /v1/credits` — View credit balance and transaction history. Auth required.
- `GET /v1/credits/packages` — List available credit packages and pricing. Public.
- `POST /v1/credits/checkout` — Create a Stripe checkout session to purchase more credits. Auth required.
- `GET /v1` — API info and endpoint listing. Public.

## Authentication

All API requests (except key creation and public endpoints) require:

```
Authorization: Bearer sc_live_YOUR_API_KEY
```

HTTP 402 is returned when credits are exhausted, with pricing headers to prompt auto-purchase.

## Pricing

| Operation | Credits | USD Cost |
|-----------|---------|----------|
| Scrape    | 1       | $0.001   |
| Extract   | 5       | $0.005   |

- 1 credit = $0.001 (one-tenth of a cent)
- 1,000 free credits included with every new API key
- Credits never expire
- No subscriptions, no minimums

## Error Codes

- `401` — Missing or invalid API key
- `402` — Insufficient credits (purchase more at /v1/credits/checkout)
- `422` — Invalid request body or schema
- `500` — Internal error (retry with exponential backoff)

## Optional Integrations

- Plugin manifest: https://shellcity.polsia.app/.well-known/ai-plugin.json
- OpenAPI schema: https://shellcity.polsia.app/openapi.json