Get started

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
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 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 as follows:

Sign in to Developer Platform and select your project.
Open API Keys and choose Create new key.
Set a descriptive name, expiration, and required permissions, then create the key.
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.

export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."

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.

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.

{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}

4. Check available tools

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

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.

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.

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.

{
  "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.

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.

{
  "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.

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 for other statuses.

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.

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

Authenticate requests for key permissions and storage
Manage execution and billing for long-running work, retries, and settlement
API reference for endpoints, statuses, and limits
Developer Platform Documentation for current examples

API

CLI

MCP server

Get started

Overview

Prerequisites

Run the API

1. Create an API key in Developer Platform

2. Set the API key and base URL

3. Check the key’s project

4. Check available tools

5. Get a quote before execution

6. Execute the quoted request

7. Poll the same execution ID

​Overview

​Prerequisites

​Run the API

​1. Create an API key in Developer Platform

​2. Set the API key and base URL

​3. Check the key’s project

​4. Check available tools

​5. Get a quote before execution

​6. Execute the quoted request

​7. Poll the same execution ID

​Related pages

Overview

Prerequisites

Run the API

1. Create an API key in Developer Platform

2. Set the API key and base URL

3. Check the key’s project

4. Check available tools

5. Get a quote before execution

6. Execute the quoted request

7. Poll the same execution ID

Related pages