# ImportExportAPI Programmatic API Access — Agent Instructions

> Machine-readable instructions for AI agents to register for ImportExportAPI, verify
> their email, extract an API key, and call live endpoints. No browser required.

## Quick Reference

| Requirement | Value |
| --- | --- |
| Signup flow | 2 API calls plus a user-provided 6-character email code |
| Register | `POST https://app.importexportapi.com/api/agents/register` |
| Verify email + get key | `POST https://app.importexportapi.com/api/agents/verify-email` |
| API base URL (all endpoints) | `https://api.importexportapi.com` |
| API auth header | `Authorization: Bearer <api_key>` |
| Starting balance | Free starter credits are granted automatically at signup |
| Main docs | `https://docs.importexportapi.com` |

## Complete Flow

### Step 1: Register

```bash
curl -X POST "https://app.importexportapi.com/api/agents/register" \
  -H "Content-Type: application/json" \
  -d '{"email": "developer@example.com", "password": "StrongP@ss1"}'
```

Success response:

```json
{ "message": "Registration successful. Check your email for the verification code.", "email": "developer@example.com" }
```

The user receives a 6-character alphanumeric code (e.g. `A3K9F2`). Ask the
human operator for this code.

### Step 2: Verify Email and Extract Credentials

```bash
curl -X POST "https://app.importexportapi.com/api/agents/verify-email" \
  -H "Content-Type: application/json" \
  -d '{"email": "developer@example.com", "code": "A3K9F2"}'
```

Success response:

```json
{
  "user": { "id": "uuid", "email": "developer@example.com" },
  "application": { "api_key": "sk_live_...", "key_prefix": "sk_live_ab12", "name": "agent" },
  "credits": { "balance": 100 }
}
```

Extract and store:

```bash
export API_BASE="https://api.importexportapi.com"
export API_KEY="<api_key from the response>"
```

**The api_key is shown exactly once.** Store it immediately. Use it as
`Authorization: Bearer $API_KEY` on every endpoint call.

## Call an Endpoint

All endpoints are available at $API_BASE — set it once:

```bash
curl -X POST "$API_BASE/v1/<endpoint-name>" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

See `https://docs.importexportapi.com` for every endpoint, parameter, and response shape, and
`https://importexportapi.com/pricing.md` for public per-endpoint pricing.

## Error Handling

| Status | Meaning | Action |
| --- | --- | --- |
| `400` | Validation error | Read `error.message` and fix request fields |
| `401` | Missing/invalid/expired key or code | Re-check the credential |
| `403` | Key lacks access, or credits exhausted | Check the account plan / top up credits |
| `429` | Rate limited | Back off; retry after delay if provided |
| `409` | Email already registered | Skip registration; request the code again via login flow |

## Agent Implementation Pseudocode

```text
1. If API_KEY is already set, verify it with a cheap authenticated call.
2. Otherwise POST /api/agents/register { email, password }.
3. Ask the human for the 6-character email code.
4. POST /api/agents/verify-email { email, code }; store application.api_key.
5. Call endpoints with Authorization: Bearer $API_KEY.
6. Treat errors by their stable error.code field, never by message text.
```

## References

- Docs index: `https://docs.importexportapi.com`
- Marketing catalogue: `llms.txt` on the marketing site
- Pricing as markdown: `pricing.md` on the marketing site