# MyAPIHQ

> The nerve center of your API ecosystem

Base URL: https://api.myapihq.com

Authentication: `Authorization: Bearer <your_api_key>`

# MyAPIHQ

Core identity and billing hub. All other services require an `api_key` and often an `org_id` from here.

## Agent onboarding (first session only)
1. `POST /hq/account/agent/create` — creates an account. Returns `{ account_id, pin, token }`. The `pin` is a permanent backup secret.
2. `POST /hq/account/create/key` (Auth: Bearer `<token>`, Body: `{"name":"AgentKey"}`) — returns `{ api_key }`. This is your persistent credential.
3. **Persist immediately:** Write a `.env` file with `MYAPI_API_KEY`, `MYAPI_ACCOUNT_ID`, `MYAPI_PIN`, and save to agent memory. On every new session, check for existing credentials before creating a new account.

## Key endpoints
- `POST /hq/orgs` — create an organization (required before using most other services)
- `GET /hq/orgs` — list organizations
- `GET /hq/billing/balance` — check balance
- `POST /hq/billing/topup` — top up balance (requires saved payment method)
- `POST /hq/billing/setup-payment` — get a URL to save a payment card

**Important:** For emails, domains, funnels, storage, and other services — fetch the llms.txt for that specific service rather than looking here.

## Key Blog Posts
- [Designing the Modern 5-Layer Identity Stack for AI Agents](https://myapihq.com/blog/5-layer-identity-stack-ai-agents): Why traditional OAuth fails autonomous systems, and how to architect scoped credentials and edge-validated tokens for machine-to-machine communication.
- [The Architecture of a Global API Gateway](https://myapihq.com/blog/architecture-global-api-gateway): Moving beyond regional latency: How distributed routing, edge compute, and anycast networks are redefining API delivery.
- [Consolidated Billing: Solving Operational Debt](https://myapihq.com/blog/consolidated-billing-solving-operational-debt): The 'Subscription Tax': Why managing dozens of isolated SaaS ledgers is draining engineering resources, and how unified billing models restore velocity.
- [Designing Idempotent APIs for Distributed Systems](https://myapihq.com/blog/designing-idempotent-apis): Handling retries, network partitions, and duplicate requests safely across global infrastructure.
- [Rate Limiting at the Network Edge](https://myapihq.com/blog/rate-limiting-network-edge): Abuse prevention without database bottlenecks: How to architect distributed counters for global APIs.


## Agent Onboarding

To use this or any other MyAPIHQ service as an autonomous agent, follow these steps:

1. **Register an Agent Account**:
   Create an agent account. Returns `account_id`, `pin`, and a `token` (JWT) in one call — no email or human required.
   ```bash
   curl -X POST https://api.myapihq.com/hq/account/agent/create \
     -H "Content-Type: application/json" \
     -d '{"label": "my-agent"}'
   ```

2. **Create a Permanent API Key**:
   Use the `token` from step 1 to create a workspace-scoped API key (`hq_live_...`).
   ```bash
   curl -X POST https://api.myapihq.com/hq/account/create/key \
     -H "Authorization: Bearer <token_from_step_1>" \
     -H "Content-Type: application/json" \
     -d '{"name": "my-agent-key"}'
   ```

3. **Authenticate**:
   All subsequent requests must include: `Authorization: Bearer <your_api_key>`.
   The JWT token from step 1 is valid for account and billing endpoints only.
   All service calls (orgs, funnels, email, domains) require the API key from step 2.

## MyAPIHQ Endpoints

### GET /hq/account/keys
**List API Keys**
Retrieve all active API keys for the authenticated user's workspace.

**Response (JSON):**
```json
Array<[Ref: APIKey]>
```


### POST /hq/account/create/key
**Create API Key**
Generate a new scoped API key for programmatic access.

**Request Body (JSON):**
```json
{
  "name": string (Required),
  "scopes": Array<string>
}
```

**Response (JSON):**
```json
{
  "status": string,
  "api_key": string,
  "name": string
}
```


### DELETE /hq/account/delete/key/{id}
**Revoke API Key**
Permanently revoke and deactivate an API key.

**Parameters:**
- `id` (path):  (type: string, Required)

**Response:** Key revoked


### POST /hq/account/register
**Register Human Account**
Create a new human account. Requires email verification.

**Request Body (JSON):**
```json
{
  "email": string (Required),
  "password": string (Required)
}
```

**Response:** Registration successful, verification email sent


### POST /hq/account/login
**Login**
Authenticate with email and password to receive a JWT.

**Request Body (JSON):**
```json
{
  "email": string (Required),
  "password": string (Required)
}
```

**Response (JSON):**
```json
{
  "token": string,
  "account_id": string
}
```


### POST /hq/account/refresh
**Refresh Token**
Exchange a refresh token cookie for a new access token.

**Response:** New access token issued


### POST /hq/account/link-agent
**Link Agent by PIN**
Link an autonomous agent account to the current human account using the agent's PIN.

**Request Body (JSON):**
```json
{
  "pin": string (Required)
}
```

**Response:** Agent linked successfully


### POST /hq/account/link-agent/accept
**Accept Agent Link**
Accept a linking request using a token (typically from an email link).

**Request Body (JSON):**
```json
{
  "token": string (Required)
}
```

**Response:** Agent linked successfully


### GET /hq/account/agents
**List Linked Agents**
Retrieve all agent accounts linked to this human account.

**Response (JSON):**
```json
Array<[Ref: Account]>
```


### GET /hq/account/agent/{agent_id}/balance
**Get Agent Balance**
Retrieve the current balance of a linked agent account.

**Parameters:**
- `agent_id` (path):  (type: string, Required)

**Response:** Agent balance


### GET /hq/account/agent/{agent_id}/usage
**Get Agent Usage**
Retrieve usage metrics for a linked agent account.

**Parameters:**
- `agent_id` (path):  (type: string, Required)

**Response:** Agent usage metrics


### POST /hq/account/agent/send-link-email
**Send Link Email**
Send an email to the agent's owner (if applicable) to request a link.

**Request Body (JSON):**
```json
{
  "email": string (Required)
}
```

**Response:** Link email sent


### GET /hq/orgs
**List Organizations**
Retrieve all organizations belonging to the authenticated user.

**Response (JSON):**
```json
Array<[Ref: Organization]>
```

---
### POST /hq/orgs
**Create Organization**
Create a new organization.

**Request Body (JSON):**
```json
{
  "name": string,
  "description": string,
  "business_sector": string,
  "logo_url": string,
  "color_palette": object,
  "font_family": string,
  "privacy_policy_url": string,
  "cookie_policy_url": string,
  "terms_url": string,
  "gdpr_enabled": boolean,
  "default_language": string,
  "tracking": object,
  "privacy_policy_md": string - Privacy policy content in markdown. Auto-generated by AI if not provided when creating a funnel.,
  "terms_md": string - Terms of service content in markdown. Auto-generated by AI if not provided when creating a funnel.,
  "cookie_policy_md": string - Cookie policy content in markdown. Auto-generated by AI if not provided when creating a funnel.
}
```

**Response:** Organization created


### GET /hq/orgs/{id}
**Get Organization**
Retrieve organization details.

**Parameters:**
- `id` (path):  (type: string, Required)

**Response:** Organization details

---
### PATCH /hq/orgs/{id}
**Update Organization**
Update organization fields (supports partial updates).

**Parameters:**
- `id` (path):  (type: string, Required)

**Request Body (JSON):**
```json
{
  "name": string,
  "description": string,
  "business_sector": string,
  "logo_url": string,
  "color_palette": object,
  "font_family": string,
  "privacy_policy_url": string,
  "cookie_policy_url": string,
  "terms_url": string,
  "gdpr_enabled": boolean,
  "default_language": string,
  "tracking": object,
  "privacy_policy_md": string - Privacy policy content in markdown.,
  "terms_md": string - Terms of service content in markdown.,
  "cookie_policy_md": string - Cookie policy content in markdown.
}
```

**Response:** Organization updated

---
### DELETE /hq/orgs/{id}
**Delete Organization**
Delete an organization and all its associated assets, funnels, webhooks, and leads.

**Parameters:**
- `id` (path):  (type: string, Required)


### POST /hq/orgs/{id}/webhooks
**Register Webhook**
Register a webhook for an organization. This webhook is notified when organization details are updated.

**Parameters:**
- `id` (path):  (type: string, Required)

**Request Body (JSON):**
```json
{
  "url": string (Required),
  "name": string,
  "description": string
}
```

**Response:** Webhook registered

---
### GET /hq/orgs/{id}/webhooks
**List Organization Webhooks**
Retrieve all webhooks registered for the given organization.

**Parameters:**
- `id` (path):  (type: string, Required)

**Response (JSON):**
```json
Array<{
  "id": string,
  "url": string,
  "name": string,
  "description": string,
  "created_at": string
}>
```


### DELETE /hq/orgs/{id}/webhooks/{webhook_id}
**Delete Organization Webhook**
Remove a registered webhook from an organization.

**Parameters:**
- `id` (path):  (type: string, Required)
- `webhook_id` (path):  (type: string, Required)


### POST /hq/account/agent/create
**Register an Agent Account**
Create a new anonymous agent account. This returns a unique PIN that can be used to generate access tokens. Keep this PIN secret.

**Response (JSON):**
```json
{
  "pin": string
}
```


### POST /hq/account/agent/token
**Generate Agent Token**
Exchange an Agent PIN for a short-lived access token.

**Request Body (JSON):**
```json
{
  "pin": string (Required)
}
```

**Response (JSON):**
```json
{
  "token": string
}
```


### POST /hq/billing/topup
**Top Up Balance**
Add credit to the workspace balance. This endpoint requires an active payment method to be registered via POST /hq/billing/setup-payment.

**Request Body (JSON):**
```json
{
  "amount_cents": integer - The amount to top up in cents (e.g., 1000 = 0.00) (Required)
}
```

**Response (JSON):**
```json
{
  "new_balance_cents": integer,
  "new_balance_display": string
}
```


### GET /hq/billing/balance
**Get Account Balance**
Retrieve the current prepaid balance for the workspace.

**Response (JSON):**
```json
{
  "balance_cents": integer,
  "balance_display": string,
  "has_payment_method": boolean
}
```


### POST /hq/billing/setup-payment
**Setup Payment Method**
Generates a hosted checkout URL to save a payment card. The user must visit this URL, enter their card, and complete the setup. The card is then saved to the account automatically.

**Response (JSON):**
```json
{
  "success": boolean,
  "data": {
    "url": string
  },
  "error": string,
  "meta": object
}
```


### POST /hq/billing/setup-payment/confirm
**Confirm Payment Setup**
Manually confirm a payment method setup by providing the payment method ID.

**Request Body (JSON):**
```json
{
  "payment_method_id": string (Required)
}
```

**Response:** Payment method saved


### GET /hq/billing/history
**Get Billing History**
Retrieve recent billing events, including top-ups and charges.

**Response:** Billing history


### POST /hq/org-imports
**Import Brand from Domain**
Triggers an async job to scrape a domain and extract its brand kit via AI.

**Request Body (JSON):**
```json
{
  "domain": string (Required),
  "auto_accept": boolean
}
```


### GET /hq/org-imports/{job_id}
**Get Import Job**
Poll the status of an async brand import.

**Parameters:**
- `job_id` (path):  (type: string, Required)

**Response (JSON):**
```json
[Ref: ImportJob]
```


### POST /hq/org-imports/{job_id}/confirm
**Confirm Import Job**
Confirm an awaiting import job, optionally providing overrides for the extracted brand.

**Parameters:**
- `job_id` (path):  (type: string, Required)

**Request Body (JSON):**
```json
object - Optional overrides for any brand field
```

**Response (JSON):**
```json
[Ref: Organization]
```


## Pricing

Unified billing. Pay for what you use across all services.

---

## Available Ecosystem Services

MyAPIHQ is the central hub. For specialized operations, fetch the `/llms.txt` of the corresponding service below:

- [mydomainapi.com](https://mydomainapi.com/llms.txt): Domains & DNS: Search, purchase, and configure DNS. Required prerequisite for myfunnelapi.com and myemailapi.com.
- [myemailapi.com](https://myemailapi.com/llms.txt): Transactional Email: Send emails and track delivery status. Requires a domain registered in your workspace.
- [myfunnelapi.com](https://myfunnelapi.com/llms.txt): Funnels & Websites: Programmatically deploy high-converting landing pages. Requires a custom domain managed via mydomainapi.com.
- [mystorageapi.com](https://mystorageapi.com/llms.txt): Object Storage: Upload images, manage assets, and serve them via global CDN. Ideal for storing images used in your funnels or emails.
- [mywebhookapi.com](https://mywebhookapi.com/llms.txt): Inbound Webhooks: Provision unique inbound URLs per organisation, store payloads, and fan out to workflow automations.
- [myworkflowapi.com](https://myworkflowapi.com/llms.txt): Workflow Automation: Trigger single-step workflows from webhooks. Resolves {{payload.field}} variables, sends emails with tracking, and retries automatically.

For agent onboarding, always fetch the specific service's /llms.txt for exact OpenAPI endpoints and usage instructions.