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

# Primeros pasos

> Configura una clave y utiliza cURL para solicitar un presupuesto, ejecutar una herramienta y obtener el resultado.

## Descripción general

Este ejemplo usa `web_search` para preparar una clave, solicitar un presupuesto gratuito, ejecutar y obtener el resultado. Solo necesitas un shell compatible con Bash y cURL, sin un SDK específico.

## Requisitos previos

Prepara estos cinco elementos:

* Una cuenta de NoimosAI con acceso a [Developer Platform](https://platform.noimosai.com)
* Un proyecto de Developer Platform con acceso API habilitado
* Una clave de desarrollador con prefijo `nmp_` y los permisos necesarios
* Un shell compatible con Bash
* cURL, jq y uuidgen

Para ejecutar trabajo de pago, revisa también el saldo prepagado en USD y los límites mensuales del proyecto. Consulta los permisos en [Autenticar solicitudes](https://docs.noimosai.com/es/developers/api/authentication.md).

Si no aparece ningún proyecto accesible, pide a un `OWNER` o `ADMIN` de la organización que cree uno o te añada. Las claves se crean dentro de un proyecto al que perteneces.

## Ejecutar la API

Sigue estos siete pasos para tu primera ejecución.

### 1. Crear una clave en Developer Platform

Un `ADMIN` o `DEVELOPER` del proyecto puede crear una clave en [Developer Platform](https://platform.noimosai.com):

1. Inicia sesión y selecciona el proyecto.
2. Abre **Claves API** y elige **Crear nueva clave**.
3. Indica un nombre descriptivo, vencimiento y permisos; crea la clave.
4. Guarda la clave secreta en un lugar seguro: solo se muestra una vez.

Este ejemplo requiere `project:read`, `tools:read`, `tools:execute` y `executions:read`. Para otros usos, concede solo los permisos necesarios.

### 2. Configurar la clave y la URL base

Guarda la clave y la URL base en variables de entorno para evitar escribir secretos directamente en el historial o código fuente.

```bash theme={null}
export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."
```

> [!WARNING]
>
> La clave solo se muestra una vez al crearla. No la guardes en Git, documentos compartidos ni JavaScript del cliente.

### 3. Comprobar el proyecto de la clave

Comprueba primero que la clave corresponde al proyecto previsto de Developer Platform.

```bash theme={null}
curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/project" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY"
```

La respuesta correcta incluye ID de organización, ID y nombre del proyecto en `data`. Si no es el proyecto esperado, revisa la clave antes de ejecutar trabajo de pago.

```json theme={null}
{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}
```

### 4. Consultar las herramientas disponibles

Obtén nombres, descripciones, esquemas, ejemplos, disponibilidad y precios actuales.

```bash theme={null}
NOIMOS_TOOLS_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

echo "$NOIMOS_TOOLS_RESPONSE" | jq
```

Revisa `executionEnabled` en la respuesta general y `available` en la herramienta. Usa la respuesta como referencia actual, sin asumir cantidades, modelos, esquemas o precios fijos.

Filtra la respuesta guardada para consultar solo `web_search`.

```bash theme={null}
echo "$NOIMOS_TOOLS_RESPONSE" | jq \
  '.data.tools[] | select(.name == "web_search") | {
    name,
    description,
    available,
    inputSchema,
    example,
    models,
    price
  }'
```

### 5. Solicitar un presupuesto antes de ejecutar

Envía el nombre de herramienta y sus argumentos para obtener la versión de precios y la reserva máxima. Esto no inicia trabajo de pago.

```bash theme={null}
NOIMOS_QUOTE_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/quote" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "tool": "web_search",
    "arguments": {
      "query": "content marketing trends",
      "count": 5
    }
  }')

echo "$NOIMOS_QUOTE_RESPONSE" | jq
```

El presupuesto devuelve `priceVersion` y `maximumChargeMicros`, necesarios para ejecutar. Reutilízalos sin modificarlos ni calcularlos. `maximumChargeMicros` es un entero en millonésimas de USD: 1 USD equivale a 1,000,000 micros.

```json theme={null}
{
  "data": {
    "tool": "web_search",
    "priceVersion": "...",
    "currency": "usd",
    "minimumChargeMicros": 0,
    "maximumChargeMicros": 0,
    "expiresAt": "..."
  }
}
```

Los importes anteriores solo ilustran el formato. El siguiente paso obtiene los valores reales de la respuesta guardada.

### 6. Ejecutar la solicitud presupuestada

Usa la misma herramienta y argumentos y añade la versión de precios y reserva máxima recibidas. Incluye una clave de idempotencia que identifique la solicitud lógica.

```bash theme={null}
export NOIMOS_PRICE_VERSION=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.priceVersion')
export NOIMOS_MAXIMUM_CHARGE_MICROS=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.maximumChargeMicros')
export NOIMOS_IDEMPOTENCY_KEY=$(uuidgen)

NOIMOS_EXECUTION_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/web_search" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NOIMOS_IDEMPOTENCY_KEY" \
  --data "$(jq -n \
    --arg priceVersion "$NOIMOS_PRICE_VERSION" \
    --argjson maximumChargeMicros "$NOIMOS_MAXIMUM_CHARGE_MICROS" \
    '{
      tool: "web_search",
      arguments: {
        query: "content marketing trends",
        count: 5
      },
      priceVersion: $priceVersion,
      maximumChargeMicros: $maximumChargeMicros
    }')")

echo "$NOIMOS_EXECUTION_RESPONSE" | jq
export NOIMOS_EXECUTION_ID=$(echo "$NOIMOS_EXECUTION_RESPONSE" | jq -r '.data.id')
```

Este ejemplo reutiliza el presupuesto del paso 5 y genera una clave con `uuidgen`. La aceptación devuelve HTTP 202 y un ID de ejecución.

```json theme={null}
{
  "data": {
    "id": "EXECUTION_ID",
    "tool": "web_search",
    "status": "queued",
    "reservedMicros": 0,
    "chargedMicros": 0
  }
}
```

También se devuelven versión de precios, salida, errores y fechas. `chargedMicros: 0` durante el proceso no significa que se haya liquidado como gratuito.

### 7. Consultar el mismo ID de ejecución

Usa el ID guardado en el paso 6 y consulta a intervalos de al menos cinco segundos hasta que termine.

```bash theme={null}
while true; do
  NOIMOS_STATUS_RESPONSE=$(curl --fail-with-body \
    "$NOIMOS_PLATFORM_API_URL/tools/executions/$NOIMOS_EXECUTION_ID" \
    -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

  echo "$NOIMOS_STATUS_RESPONSE" | jq
  NOIMOS_STATUS=$(echo "$NOIMOS_STATUS_RESPONSE" | jq -r '.data.status')

  case "$NOIMOS_STATUS" in
    succeeded|failed|cancelled|needs_review) break ;;
  esac

  sleep 5
done
```

`queued`, `running` y `waiting` indican procesamiento pendiente. Con `succeeded`, lee `output` y `chargedMicros`. Consulta otros estados en [Gestionar ejecución y facturación](https://docs.noimosai.com/es/developers/api/execution-and-billing.md).

> [!WARNING]
>
> Si desconoces la respuesta, no reenvíes con una nueva clave de idempotencia. El mismo cuerpo y la misma clave permiten recuperar la ejecución ya aceptada.

## Páginas relacionadas

Después, consulta las páginas pertinentes:

* [Autenticar solicitudes](https://docs.noimosai.com/es/developers/api/authentication.md): permisos y almacenamiento de claves
* [Gestionar ejecución y facturación](https://docs.noimosai.com/es/developers/api/execution-and-billing.md): procesos largos, reintentos y liquidación
* [Referencia de la API](https://docs.noimosai.com/es/developers/api/reference.md): endpoints, estados y límites
* [Documentación](https://platform.noimosai.com/docs) de Developer Platform: ejemplos actuales


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