AI Tools API

curl -X GET 'https://auth.nucleoplatform.com/api/mcp/context?org_id=7' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

const res = await fetch("https://auth.nucleoplatform.com/api/mcp/context?org_id=7", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    Accept: "application/json",
  },
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://auth.nucleoplatform.com/api/mcp/context?org_id=7', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

{
  "user": {
    "id": 42,
    "name": "Giulia Rossi",
    "email": "giulia.rossi@acme.example",
    "language": "it",
    "is_internal": false
  },
  "companies": [
    {
      "id": 7,
      "slug": "acme",
      "name": "Acme Apparel",
      "is_internal": false,
      "is_demo": false,
      "disabled_sections": [
        "pos"
      ],
      "modules": [
        {
          "slug": "catalog",
          "name": "Catalog",
          "role": "editor",
          "api_base_url": "https://api-catalog.nucleoplatform.com",
          "connector_enabled": true
        },
        {
          "slug": "commerce",
          "name": "Commerce",
          "role": "viewer",
          "api_base_url": "https://api-commerce.nucleoplatform.com",
          "connector_enabled": true
        },
        {
          "slug": "intelligence",
          "name": "Intelligence",
          "role": "viewer",
          "api_base_url": "https://api-intelligence.nucleoplatform.com",
          "connector_enabled": false
        }
      ]
    }
  ],
  "active_company_id": 7,
  "active_company_source": "only"
}

{
  "message": "Unauthenticated."
}

curl -X PUT https://auth.nucleoplatform.com/api/mcp/company \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "organization_id": 7
}'

const res = await fetch("https://auth.nucleoplatform.com/api/mcp/company", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "organization_id": 7
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('PUT', 'https://auth.nucleoplatform.com/api/mcp/company', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
    ],
    'json' => [
        'organization_id' => 7,
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

{
  "user": {
    "id": 1,
    "name": "string",
    "email": "jane@example.com",
    "language": "en",
    "is_internal": true
  },
  "companies": [
    {
      "id": 1,
      "slug": "string",
      "name": "string",
      "is_internal": true,
      "is_demo": true,
      "disabled_sections": [
        "string"
      ],
      "modules": [
        {
          "slug": "brain",
          "name": "string",
          "role": "string",
          "api_base_url": "https://shop.acme.example",
          "connector_enabled": true
        }
      ]
    }
  ],
  "active_company_id": 1,
  "active_company_source": "claim"
}

{
  "message": "Unauthenticated."
}

{
  "error": "company_forbidden",
  "message": "You have no access to this company."
}

{
  "message": "The organization id field is required.",
  "errors": {
    "organization_id": [
      "The organization id field is required."
    ]
  }
}

curl -X GET https://api-catalog.nucleoplatform.com/api/v1/ai-tools \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'X-Nucleo-Company: 7' \
  -H 'X-Nucleo-Language: en' \
  -H 'X-Nucleo-AI-Tools-Version: 1' \
  -H 'X-Nucleo-Request-Id: 2f9c1e4a-7b3d-4c5e-9f8a-1b2c3d4e5f6a' \
  -H 'X-Nucleo-Store: acme-eu' \
  -H 'If-None-Match: "5f1d3b0c9a4e2b7d8c6f1a0e3b2d4c5a6f7e8d9c"' \
  -H 'Accept: application/json'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/v1/ai-tools", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "X-Nucleo-Company": "7",
    "X-Nucleo-Language": "en",
    "X-Nucleo-AI-Tools-Version": "1",
    "X-Nucleo-Request-Id": "2f9c1e4a-7b3d-4c5e-9f8a-1b2c3d4e5f6a",
    "X-Nucleo-Store": "acme-eu",
    "If-None-Match": "\"5f1d3b0c9a4e2b7d8c6f1a0e3b2d4c5a6f7e8d9c\"",
    Accept: "application/json",
  },
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://api-catalog.nucleoplatform.com/api/v1/ai-tools', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'X-Nucleo-Company' => '7',
        'X-Nucleo-Language' => 'en',
        'X-Nucleo-AI-Tools-Version' => '1',
        'X-Nucleo-Request-Id' => '2f9c1e4a-7b3d-4c5e-9f8a-1b2c3d4e5f6a',
        'X-Nucleo-Store' => 'acme-eu',
        'If-None-Match' => '"5f1d3b0c9a4e2b7d8c6f1a0e3b2d4c5a6f7e8d9c"',
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

{
  "version": 1,
  "module": "commerce",
  "company": {
    "id": 7,
    "slug": "acme",
    "name": "Acme Apparel"
  },
  "language": "en",
  "instructions": "Nucleo Commerce: Customer care (internal tickets between Customer Service, Logistics and the other teams; customer requests from the helpdesk, for the Customer Service team only), POS (points of sale, on-hand stock, inbound deliveries, transfers and returns) and Orders (the OMS: orders, customers, returns, shipments, sellable stock, routing, anomalies, fulfillment KPIs). Ticket codes look like TK-0029. Start from search_tickets or list_customer_requests (search_orders for orders), then read the detail. Everything here is read-only: nothing changes data, and reading a ticket does not mark it as read.",
  "tools": [
    {
      "name": "get_order",
      "title": "Get order",
      "description": "Orders (Nucleo OMS). One order in full: customer, address, items, ship-from location, holds, shipments with tracking, returns and anomalies.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "order": {
            "type": "string",
            "maxLength": 120,
            "description": "Order number (e.g. #1042) or id."
          }
        },
        "required": [
          "order"
        ]
      },
      "permission": "oms.read",
      "side_effects": "read",
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      },
      "tags": [
        "oms",
        "orders"
      ]
    }
  ],
  "generated_at": "2026-10-04T09:15:00+02:00"
}

{
  "error": "company_required",
  "message": "Missing or invalid X-Nucleo-Company header."
}

{
  "message": "Azienda attiva mancante (header X-Nucleo-Company)."
}

{
  "message": "Unauthenticated."
}

{
  "error": "company_forbidden",
  "message": "Nucleo Commerce is not available to you in this company."
}

{
  "message": "Hub is not provisioned for this company."
}

{
  "error": "unsupported_version",
  "message": "Unsupported ai-tools contract version.",
  "supported": [
    1
  ]
}

{
  "error": "company_not_ready",
  "message": "Nucleo Intelligence is not set up yet for this company: open it once in the Nucleo app."
}

{
  "message": "Too Many Attempts."
}

curl -X POST https://api-catalog.nucleoplatform.com/api/v1/ai-tools/search_orders \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'X-Nucleo-Company: 7' \
  -H 'X-Nucleo-Language: en' \
  -H 'X-Nucleo-AI-Tools-Version: 1' \
  -H 'X-Nucleo-Request-Id: 2f9c1e4a-7b3d-4c5e-9f8a-1b2c3d4e5f6a' \
  -H 'X-Nucleo-Store: acme-eu' \
  -H 'X-Nucleo-Client: acme-agent/1.4' \
  -H 'Content-Type: application/json' \
  -d '{
  "arguments": {
    "query": "giulia.rossi@acme.example",
    "status": "shipped",
    "per_page": 5
  },
  "context": {
    "client": {
      "name": "acme-agent",
      "version": "1.4"
    }
  }
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/v1/ai-tools/search_orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "X-Nucleo-Company": "7",
    "X-Nucleo-Language": "en",
    "X-Nucleo-AI-Tools-Version": "1",
    "X-Nucleo-Request-Id": "2f9c1e4a-7b3d-4c5e-9f8a-1b2c3d4e5f6a",
    "X-Nucleo-Store": "acme-eu",
    "X-Nucleo-Client": "acme-agent/1.4",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "arguments": {
      "query": "giulia.rossi@acme.example",
      "status": "shipped",
      "per_page": 5
    },
    "context": {
      "client": {
        "name": "acme-agent",
        "version": "1.4"
      }
    }
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://api-catalog.nucleoplatform.com/api/v1/ai-tools/search_orders', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'X-Nucleo-Company' => '7',
        'X-Nucleo-Language' => 'en',
        'X-Nucleo-AI-Tools-Version' => '1',
        'X-Nucleo-Request-Id' => '2f9c1e4a-7b3d-4c5e-9f8a-1b2c3d4e5f6a',
        'X-Nucleo-Store' => 'acme-eu',
        'X-Nucleo-Client' => 'acme-agent/1.4',
    ],
    'json' => [
        'arguments' => [
            'query' => 'giulia.rossi@acme.example',
            'status' => 'shipped',
            'per_page' => 5,
        ],
        'context' => [
            'client' => [
                'name' => 'acme-agent',
                'version' => '1.4',
            ],
        ],
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

{
  "content": [
    {
      "type": "text",
      "text": "{\n    \"total\": 1,\n    \"orders\": [ { \"number\": \"#1042\", \"status\": \"shipped\" } ]\n}"
    }
  ],
  "structuredContent": {
    "total": 1,
    "orders": [
      {
        "number": "#1042",
        "status": "shipped",
        "customer": "Giulia Rossi",
        "total": "89.00 EUR",
        "url": "https://app.nucleoplatform.com/commerce/orders/1042"
      }
    ]
  },
  "isError": false
}

{
  "content": [
    {
      "type": "text",
      "text": "{\n    \"error\": \"not_found\",\n    \"message\": \"Order #1099 not found.\"\n}"
    }
  ],
  "structuredContent": {
    "error": "not_found",
    "message": "Order #1099 not found."
  },
  "isError": true
}

{
  "content": [
    {
      "type": "text",
      "text": "{ \"error\": \"confirmation_required_in_app\", \"applied\": false, ... }"
    }
  ],
  "structuredContent": {
    "error": "confirmation_required_in_app",
    "applied": false,
    "message": "Nothing was changed. This change needs an explicit confirmation that only happens inside Nucleo Catalog (deletions, whole-object replacements, bulk or storefront-facing changes, imports, publishing, or more than 3 writes / 5 products within 10 minutes). `will_do` is the preview: show it to the user and ask them to run it with Atomo in Nucleo Catalog, or split it into smaller changes.",
    "will_do": {
      "summary": "Set price 29.90 EUR on 40 products in price list Retail EU"
    }
  },
  "isError": true
}

{
  "error": "company_required",
  "message": "Missing or invalid X-Nucleo-Company header."
}

{
  "message": "Azienda attiva mancante (header X-Nucleo-Company)."
}

{
  "message": "Unauthenticated."
}

{
  "error": "permission_denied",
  "permission": "dashboard.private",
  "message": "This dashboard is private: only its owner and Intelligence admins can open it."
}

{
  "error": "company_forbidden",
  "message": "Nucleo Commerce is not available to you in this company."
}

{
  "error": "unknown_tool",
  "message": "Unknown tool: search_invoices"
}

{
  "error": "unsupported_version",
  "message": "Unsupported ai-tools contract version.",
  "supported": [
    1
  ]
}

{
  "error": "company_not_ready",
  "message": "Nucleo Intelligence is not set up yet for this company: open it once in the Nucleo app."
}

{
  "error": "invalid_arguments",
  "message": "The per page field must not be greater than 50.",
  "errors": {
    "per_page": [
      "The per page field must not be greater than 50."
    ]
  }
}

{
  "error": "invalid_arguments",
  "message": "Invalid arguments for this tool.",
  "details": [
    {
      "field": "product",
      "error": "required"
    }
  ]
}

{
  "message": "Too Many Attempts."
}