> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Review the base URL, endpoints, responses, errors, and usage limits.

## Overview

This page summarizes connection details, endpoints, response formats, errors, and limits shared by the Developer Platform API. Retrieve tool-specific input schemas and current pricing with `GET /tools`.

## Base URL and common headers

Append all paths to this base URL.

```text theme={null}
https://api.noimosai.com/noimosToolBridge
```

Authenticate with a Developer Platform API key. Include Content-Type when sending a JSON body.

```http theme={null}
Authorization: Bearer nmp_...
Content-Type: application/json
```

Paid execution also requires this header.

```http theme={null}
Idempotency-Key: request-unique-id
```

## Endpoints

These are the main public API endpoints.

| Method and path | Required permission | Purpose |
| - | - | - |
| `GET /tools/project` | `project:read` | Read the key's organization and project |
| `GET /tools/usage` | `usage:read` | Read settled request counts and USD charges for the current UTC month |
| `GET /tools` | `tools:read` | Retrieve tools, schemas, examples, availability, and pricing |
| `POST /tools/quote` | `tools:read` | Get a free quote for the maximum reservation for your input |
| `POST /tools/upload` | `tools:execute` | Store explicitly supplied inputs privately in the project |
| `POST /tools/{tool}` | `tools:execute` | Reserve the spending cap and register paid work |
| `GET /tools/executions` | `executions:read` | List project executions |
| `GET /tools/executions/{id}` | `executions:read` | Retrieve execution status, results, and settled charges |
| `POST /tools/executions/{id}/cancel` | `tools:execute` | Request cancellation |
| `GET /tools/executions/{id}/artifacts/{artifactId}/download` | `executions:read` | Retrieve an expiring URL for a generated file |

Filter `GET /tools/executions` with `limit`, `before`, `status`, and `tool`. `limit` accepts 1–100 and defaults to 20.

## Tool catalog

The `data` from `GET /tools` includes the catalog-wide price version, currency, execution availability, and tool list.

Each tool provides the following:

* `name` — Tool name to use in the execution URL and request body
* `description` and `category` — Purpose and classification
* `available` — Whether required external services are configured and the tool is available
* `inputSchema` and `example` — Input JSON Schema and example
* `models` — Available models with per-model examples, availability, and pricing descriptions
* `price` — Minimum charge, billing unit, and pricing description

`available: true` alone does not guarantee execution. Catalog-wide `executionEnabled`, key permissions, prepaid balance, and monthly caps also apply.

## Response format

Successful responses generally place the result in `data`.

```json theme={null}
{
  "data": {}
}
```

Errors include a status and message in `error`.

```json theme={null}
{
  "error": {
    "status": "PERMISSION_DENIED",
    "message": "platform_api_key_scope_required"
  }
}
```

All responses use `Cache-Control: no-store`. Do not store API keys, results, or expiring URLs in shared caches.

## Handle errors

Check the cause based on the returned status before retrying.

| HTTP | Meaning | Action |
| - | - | - |
| `200` | Successful retrieval or the same completed execution | Process `data` |
| `202` | Asynchronous work accepted | Save the execution ID and wait at least five seconds before polling |
| `400` | Invalid input, quote, or state | Check the catalog and quote |
| `401` | Authentication failed | Check Authorization, expiration, and revocation |
| `403` | Permission denied | Check key permissions and project access |
| `404` | Endpoint, operation, or artifact unavailable | Check the path, availability, and expiration |
| `409` | Idempotency key used for a different request | Check the original body and key; avoid creating another execution |
| `429` | Request limit, balance, or monthly cap reached | Check the applicable limit and balance |
| `503` | Execution or external service temporarily unavailable | Check whether paid work was accepted before retrying |

## Usage limits

Account for these limits in your client.

| Resource | Limit |
| - | - |
| Standard JSON request | 64 KiB in UTF-8 |
| Uploaded file size | 12 MiB |
| Upload formats | JPEG, PNG, WAV, MP3, MP4 |
| Requests | 120 per API key per fixed one-minute window |
| Polling interval | At least five seconds |
| Steps per execution | Up to 20 |
| Generated file retention | 30 days |
| Download URL validity | Up to five minutes |

Request counts include catalog reads, quotes, uploads, executions, polling, and retries. Avoid unnecessarily frequent polling to prevent 429 responses.

## Upload inputs

To use local images, audio, or video, send the MIME type and Base64 data to `POST /tools/upload`.

```json theme={null}
{
  "mimeType": "audio/wav",
  "data": "BASE64_DATA"
}
```

Success returns an `id` usable as `fileId`, format, size, SHA-256, and expiration. Pass it to tool-specific fields such as `source` in the format shown by the catalog. Identical content in the same project returns the same ID; retention does not extend beyond the original upload's expiration.

## Related pages

See these pages for authentication and execution.

* [Authenticate requests](https://docs.noimosai.com/developers/api/authentication.md)
* [Manage execution and billing](https://docs.noimosai.com/developers/api/execution-and-billing.md)
* [Documentation](https://platform.noimosai.com/docs)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.