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

# Get started

> Set up an API key and use cURL to request a quote, execute a tool, and retrieve the result.

## Overview

This walkthrough uses `web_search` to prepare an API key, get a free quote, execute a tool, and retrieve the result. Complete your first execution with a Bash-compatible shell and cURL, without a language-specific SDK.

## Prerequisites

Prepare these five things before calling the API:

* A NoimosAI account that can sign in to [Developer Platform](https://platform.noimosai.com)
* A Developer Platform project with API access enabled
* A developer API key beginning with `nmp_` and the required permissions
* A Bash-compatible shell
* cURL, jq, and uuidgen

For paid execution, also check the project's available prepaid USD balance and monthly limits. See [Authenticate requests](https://docs.noimosai.com/developers/api/authentication.md) for key permissions.

If no accessible project appears in Developer Platform, ask an organization `OWNER` or `ADMIN` to create a project or grant you membership. Create API keys within a project you belong to.

## Run the API

Follow these seven steps for your first execution.

### 1. Create an API key in Developer Platform

A project `ADMIN` or `DEVELOPER` can create a key in [Developer Platform](https://platform.noimosai.com) as follows:

1. Sign in to Developer Platform and select your project.
2. Open **API Keys** and choose **Create new key**.
3. Set a descriptive name, expiration, and required permissions, then create the key.
4. Save the secret key in a secure location; it is shown only once.

This walkthrough requires `project:read`, `tools:read`, `tools:execute`, and `executions:read`. For other use cases, select only the permissions you need.

### 2. Set the API key and base URL

Set the API key and base URL as environment variables to avoid writing secrets directly into command history or source code.

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

> [!WARNING]
>
> The key is shown only once when created. Do not save it in Git repositories, shared documents, or client-side JavaScript.

### 3. Check the key's project

First, verify that the key connects to the intended Developer Platform project.

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

A successful response contains the organization ID, project ID, and project name in `data`. If the project is unexpected, check the key before executing paid work.

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

### 4. Check available tools

Retrieve current tool names, descriptions, input schemas, examples, availability, and pricing.

```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
```

Check the response-level `executionEnabled` and your tool's `available`. Treat this response as the current source of truth instead of assuming fixed tool counts, models, schemas, or prices.

To inspect only `web_search`, filter the saved response.

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

### 5. Get a quote before execution

Send the tool name and arguments to receive the price version and maximum reservation. This does not start paid work.

```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
```

A successful quote returns `priceVersion` and `maximumChargeMicros`, both required for execution. Reuse these values as returned; you do not need to calculate them. `maximumChargeMicros` is an integer in millionths of a USD: 1 USD equals 1,000,000 micros.

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

The amounts above only illustrate the response format. The next step reads the actual values from your saved response.

### 6. Execute the quoted request

Use the same tool and arguments as the quote, adding the returned price version and maximum reservation. Include an idempotency key that identifies this logical request.

```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')
```

This example reuses the quote from step 5 and generates a new idempotency key with `uuidgen`. Accepted requests return HTTP 202 and an execution ID.

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

The response also contains the price version, output, errors, and timestamps. `chargedMicros: 0` while processing does not mean the execution has been settled as free.

### 7. Poll the same execution ID

Use the execution ID saved in step 6 and poll at intervals of at least five seconds until completion.

```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`, and `waiting` mean processing is ongoing. At `succeeded`, read `output` and `chargedMicros`. See [Manage execution and billing](https://docs.noimosai.com/developers/api/execution-and-billing.md) for other statuses.

> [!WARNING]
>
> If the execution response is unknown, do not resend with a new idempotency key. Reusing the same body and key retrieves the same accepted execution.

## Related pages

After this walkthrough, read the pages relevant to your implementation:

* [Authenticate requests](https://docs.noimosai.com/developers/api/authentication.md) for key permissions and storage
* [Manage execution and billing](https://docs.noimosai.com/developers/api/execution-and-billing.md) for long-running work, retries, and settlement
* [API reference](https://docs.noimosai.com/developers/api/reference.md) for endpoints, statuses, and limits
* Developer Platform [Documentation](https://platform.noimosai.com/docs) for current examples


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