> ## 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.

# Referencia de la API

> URL base, endpoints, respuestas, errores y límites de uso.

## Descripción general

Esta página resume conexión, endpoints, respuestas, errores y límites comunes de la API de Developer Platform. Usa `GET /tools` para esquemas y precios actuales de cada herramienta.

## URL base y encabezados

Añade todas las rutas a esta URL base.

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

Autentica con una clave de Developer Platform. Añade Content-Type al enviar JSON.

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

La ejecución de pago también requiere este encabezado.

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

## Endpoints

Estos son los endpoints principales de la API pública.

| Método y ruta | Permiso requerido | Uso |
| - | - | - |
| `GET /tools/project` | `project:read` | Consultar organización y proyecto de la clave |
| `GET /tools/usage` | `usage:read` | Consultar solicitudes liquidadas y cargos del mes actual UTC |
| `GET /tools` | `tools:read` | Obtener herramientas, esquemas, ejemplos, disponibilidad y precios |
| `POST /tools/quote` | `tools:read` | Obtener gratuitamente la reserva máxima estimada para la entrada |
| `POST /tools/upload` | `tools:execute` | Guardar entradas explícitas de forma privada en el proyecto |
| `POST /tools/{tool}` | `tools:execute` | Reservar el límite de gasto y registrar trabajo de pago |
| `GET /tools/executions` | `executions:read` | Listar ejecuciones del proyecto |
| `GET /tools/executions/{id}` | `executions:read` | Obtener estado, resultados y cargo definitivo |
| `POST /tools/executions/{id}/cancel` | `tools:execute` | Solicitar cancelación |
| `GET /tools/executions/{id}/artifacts/{artifactId}/download` | `executions:read` | Obtener una URL temporal del archivo generado |

Filtra `GET /tools/executions` con `limit`, `before`, `status` y `tool`. `limit` admite 1–100; el valor predeterminado es 20.

## Catálogo de herramientas

`data` de `GET /tools` incluye versión de precios, moneda, disponibilidad de ejecución y herramientas del catálogo.

Cada herramienta proporciona:

* `name` — Nombre usado en la URL y el cuerpo de ejecución
* `description` y `category` — Uso y clasificación
* `available` — Si los servicios externos necesarios están configurados y disponibles
* `inputSchema` y `example` — JSON Schema de entrada y ejemplo
* `models` — Modelos seleccionables con ejemplos, disponibilidad y precios por modelo
* `price` — Cargo mínimo, unidad de facturación y descripción de precios

`available: true` no garantiza poder ejecutar. También se aplican `executionEnabled`, permisos, saldo y límites mensuales.

## Formato de respuesta

Las respuestas correctas suelen contener el resultado en `data`.

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

Los errores incluyen estado y mensaje en `error`.

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

Todas las respuestas usan `Cache-Control: no-store`. No guardes claves, resultados ni URL temporales en cachés compartidas.

## Gestionar errores

Revisa la causa según el estado antes de reintentar.

| HTTP | Significado | Acción |
| - | - | - |
| `200` | Consulta correcta o misma ejecución completada | Procesar `data` |
| `202` | Trabajo asíncrono aceptado | Guardar ID y esperar al menos cinco segundos para consultar |
| `400` | Entrada, presupuesto o estado inválido | Revisar catálogo y presupuesto |
| `401` | Autenticación fallida | Revisar Authorization, vencimiento y revocación |
| `403` | Permiso denegado | Revisar permisos de clave y proyecto |
| `404` | Endpoint, operación o artefacto no disponible | Revisar ruta, disponibilidad y vencimiento |
| `409` | Clave de idempotencia usada por otra solicitud | Revisar cuerpo y clave originales; evitar otra ejecución |
| `429` | Límite de solicitudes, saldo o tope mensual alcanzado | Revisar límite y saldo correspondientes |
| `503` | Ejecución o servicio externo temporalmente no disponible | Comprobar si se aceptó el trabajo de pago antes de reintentar |

## Límites de uso

Ten en cuenta estos límites en el cliente.

| Recurso | Límite |
| - | - |
| Solicitud JSON normal | 64 KiB en UTF-8 |
| Archivo subido | 12 MiB |
| Formatos de subida | JPEG, PNG, WAV, MP3, MP4 |
| Solicitudes | 120 por clave API en cada ventana fija de un minuto |
| Intervalo de consulta | Al menos cinco segundos |
| Pasos por ejecución | Hasta 20 |
| Conservación de archivos generados | 30 días |
| Validez de URL de descarga | Hasta cinco minutos |

Cuentan catálogo, presupuestos, subidas, ejecuciones, consultas y reintentos. Evita consultar con excesiva frecuencia para prevenir respuestas 429.

## Subir archivos de entrada

Para usar imágenes, audio o vídeo locales, envía tipo MIME y datos Base64 a `POST /tools/upload`.

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

La respuesta incluye un `id` utilizable como `fileId`, formato, tamaño, SHA-256 y vencimiento. Indícalo en campos como `source` según el catálogo. Contenido idéntico en el mismo proyecto devuelve el mismo ID; el plazo no se amplía desde la primera subida.

## Páginas relacionadas

Consulta estas páginas para autenticación y ejecución.

* [Autenticar solicitudes](https://docs.noimosai.com/es/developers/api/authentication.md)
* [Gestionar ejecución y facturación](https://docs.noimosai.com/es/developers/api/execution-and-billing.md)
* [Documentación](https://platform.noimosai.com/docs)


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