# REST API Reference

> Reference the implemented marketplace paths, session authentication, response conventions and pagination limits.

Canonical: https://theaimart.co/docs/rest-api-reference
Updated: 2026-10-08 · Guide version: 1.1

This reference covers the reviewed marketplace routes under `https://api.theaimart.co/api/v1`. It is separate from model inference on AIx and advertising on ADX. Account routes require the backend session JWT; public catalog reads do not require a model API key.

## Selected routes

| Method | Path | Behavior |
| --- | --- | --- |
| GET | `/apps` | Public approved app catalog; page/per_page filters |
| GET | `/apps/{id}` | App detail |
| POST | `/apps` | Submit an app or hosted-web listing with the required form fields |
| PUT | `/apps/{id}` | Update an owned listing |
| GET / POST | `/ai-agents` | Read public agents / submit an agent |
| GET / POST | `/apps/{id}/releases` | Read or create owned release records |
| GET | `/developers/analytics/overview` | Account analytics |
| GET | `/payouts/me` | Account payout history |
| GET | `/wallet` | Marketplace credits and recent transactions |
| GET | `/subscriptions/me` | Account subscriptions |
| GET | `/apps/{id}/reviews` | Public approved reviews |
| GET / POST | `/webhooks` | Manage owned receivers |

## Read-only example

```bash
curl --fail-with-body 'https://api.theaimart.co/api/v1/apps?page=1&per_page=20'
```

Use the endpoint's response object, such as `apps`, `agents`, `reviews` or `transactions`. App catalog pagination uses page/per_page, not a universal cursor envelope. IDs are opaque values; do not assume an `app_` or `usr_` prefix. Account requests can return 401/403, while malformed data, missing objects and rate limits have endpoint-specific errors.

## Requests, errors and units

Most management requests are JSON. Media uploads use the upload flow described in [Uploading Apps](/docs/uploading-apps); there is no `/apps/{id}/builds` route in this reference. Web apps use the `/apps` listing flow with a hosted URL, not `/webapps`.

Errors can contain a string `detail`, `error` or `message`; do not assume a nested error object. Preserve the HTTP status and handle the actual returned message. Listing prices are presented in USD, wallet movements are credits, and payment gateway amounts can use minor currency units. There is no universal paise/cents conversion for every API field.

## Troubleshooting and limits

Use the correct base URL, method and credential. A 403 can mean ownership rather than a missing invented scope. Back off after 429. Never retry a financial write blindly. Examples here are source-reviewed; a complete authenticated production integration still needs an authorized test account.

## Next

See [Accounts & Authentication](/docs/accounts-and-auth), [Webhooks](/docs/webhooks) and [Publishing](/docs/getting-started).