Nimbleway Agents API
The Agents API from Nimbleway — 7 operation(s) for agents.
Documentation
Documentation
https://docs.nimbleway.com/home
APIReference
https://docs.nimbleway.com/api-reference/introduction
OpenAPI Specification
openapi: 3.1.0
info:
title: Nimble SDK Agents API
version: 1.0.0
description: The AI-Native SDK for Real-Time Web Data at scale
servers:
- url: https://sdk.nimbleway.com
tags:
- name: Agents
paths:
/v1/agents/run:
post:
summary: Agent Run
description: Execute Search Agent Realtime Endpoint
tags:
- Agents
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AgentPayload'
examples:
- agent: amazon_pdp
params:
asin: B0DLKFK6LR
responses:
'200':
description: Successful Response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AgentResponse'
examples:
- url: https://www.example.com/
task_id: e8ed8ef6-2657-43ba-98d5-a5c79ea7b551
status: success
status_code: 200
data:
html: '...'
markdown: MARKDOWN
parsing: {}
cookies: {}
screenshot: iVBORw0KGgoAAAANSUhEUgAAA...
fetch_request: []
network_capture: []
browser_actions: []
headers: {}
metadata:
query_time: '2026-02-09T10:26:05.817Z'
query_duration: 1877
response_parameters:
input_url: https://www.example.com/
driver: vx8
agent: agent_name
'400':
description: Unprocessable Entity - Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error402'
'404':
description: Agent Not Found
content:
application/json:
schema:
type: object
properties:
status:
type: string
examples:
- failed
msg:
type: string
examples:
- Agent not found
required:
- status
- msg
example:
status: failed
msg: Agent not found
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/v1/agents/async:
post:
summary: Agent Async
description: Execute Search Agent Async Endpoint
tags:
- Agents
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AgentAsyncPayload'
examples:
- agent: google_search
params:
query: What happened last night in the NBA?
storage_url: s3://mu-s3-bucket.com/
storage_type: s3
callback_url: https://my-callback-url.com/
responses:
'200':
description: Async Task Created
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncResponse'
example:
status: success
task:
id: 8e8cfde8-345b-42b8-b3e2-0c61eb11e00f
state: pending
created_at: '2026-01-24T12:36:24.685Z'
modified_at: '2026-01-24T12:36:24.685Z'
input: {}
'400':
description: Unprocessable Entity - Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error402'
'404':
description: Agent Not Found
content:
application/json:
schema:
type: object
properties:
status:
type: string
examples:
- failed
msg:
type: string
examples:
- Agent not found
required:
- status
- msg
example:
status: failed
msg: Agent not found
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/v1/agents/batch:
post:
summary: Agent Batch
tags:
- Agents
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AgentBatchBody'
examples:
- inputs:
- params:
keyword: iphone 15
- params:
keyword: iphone 16
- params:
keyword: iphone 17
shared_inputs:
agent: amazon_serp
responses:
'200':
description: Agent Batch Created
content:
application/json:
schema:
$ref: '#/components/schemas/BatchResponse'
example:
batch_id: 4b0a90bf-c951-42e4-95b3-a95a65ba69fc
batch_size: 1
tasks:
- id: 123e4567-e89b-12d3-a456-426614174000
state: pending
output_url: string
created_at: '2024-01-15T10:30:00Z'
modified_at: '2024-01-15T10:35:00Z'
account_name: string
input: null
batch_id: 4b0a90bf-c951-42e4-95b3-a95a65ba69fc
status_code: 200
api_type: extract
'400':
description: Unprocessable Entity - Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error402'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/v1/agents/generations:
post:
tags:
- Agents
summary: Generate Agent
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/CreateAgentGenerationRequest'
- $ref: '#/components/schemas/CreateAgentRefinementRequest'
title: Request
examples:
- prompt: I want an agent for books.toscrape.com category pages
agent_name: books_toscrape_categories_nkjansdkj
url: books.toscrape.com
input_schema:
type: object
properties:
category:
type: string
output_schema:
type: object
properties:
name:
type: string
price:
type: string
url:
type: string
availability:
type: string
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentGenerationResponse'
example:
id: 86441962-c8f5-4c24-b271-ee877d2dd865
status: queued
agent_name: books_toscrape_categories_nkjansdkj_2026_03_24_zco2isqi
source_version_id: c51d09fc-c8f2-4b3a-a9bc-eaab88316217
created_at: '2026-03-24T19:19:39.300002+00:00'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error402'
'422':
description: Unprocessable Entity - Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
security:
- BearerAuth: []
/v1/agents/generations/{generation_id}:
get:
tags:
- Agents
summary: Get Generation
security:
- BearerAuth: []
parameters:
- name: generation_id
in: path
required: true
schema:
type: string
format: uuid
title: Generation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentGenerationResponse'
example:
id: 86441962-c8f5-4c24-b271-ee877d2dd865
status: success
agent_name: books_toscrape_categories_nkjansdkj_2026_03_24_zco2isqi
source_version_id: c51d09fc-c8f2-4b3a-a9bc-eaab88316217
generated_version_id: fee30209-2439-459b-985a-ba7f8d8d2325
generated_version:
id: fee30209-2439-459b-985a-ba7f8d8d2325
agent_name: books_toscrape_categories_nkjansdkj_2026_03_24_zco2isqi
version_number: 2
metadata:
vertical: Other
data_source: books.toscrape.com
display_name: books_toscrape_categories_nkjansdkj
tags: []
domain: books.toscrape.com
is_displayed: false
steps: []
artifacts: {}
summary: 'Done! The agent for **books.toscrape.com** category pages is fully configured and preview ran successfully. Here''s a summary of what was set up:
- **Browsing**: Navigates to category pages using a URL template with `category_slug` and `category_id` as inputs (e.g., `mystery` / `3`)
- **Parsing**: Extracts book data — `name`, `price`, `url`, and `availability` — from each listing on the category page'
created_at: '2026-03-24T19:19:39.300002+00:00'
started_at: '2026-03-24T19:19:39.307295+00:00'
completed_at: '2026-03-24T19:22:01.638660+00:00'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error402'
'422':
description: Unprocessable Entity - Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/v1/agents:
get:
tags:
- Agents
security:
- BearerAuth: []
summary: List Agents
parameters:
- name: privacy
in: query
required: false
schema:
description: Filter by privacy level
default: all
type: string
enum:
- public
- private
- all
description: Filter by privacy level
- name: managed_by
in: query
required: false
schema:
description: Filter by who manage the agent
type: string
enum:
- nimble
- community
- self_managed
description: Filter by who manage the agent
- name: limit
in: query
required: false
schema:
type: integer
maximum: 250
minimum: 1
description: Number of results per page
default: 100
title: Limit
description: Number of results per page
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Pagination offset
default: 0
title: Offset
description: Pagination offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
allOf:
- type: array
items:
properties:
name:
type: string
title: Name
is_public:
type: boolean
title: Is Public
managed_by:
type: string
title: Managed By
display_name:
type: string
title: Display Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
vertical:
anyOf:
- type: string
- type: 'null'
title: Vertical
entity_type:
anyOf:
- type: string
- type: 'null'
title: Entity Type
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
type: object
required:
- name
- is_public
- display_name
title: Agents
title: Response List Agents
examples:
- - name: aldi_clp
is_public: true
display_name: Aldi Category Landing Page
description: The Aldi Browse Products agent extracts structured product listings from Aldi’s category pages. This agent is ideal for monitoring category-level assortment, analyzing competitive inventory, and powering product discovery and pricing intelligence use cases
vertical: Ecommerce
entity_type: Category Landing Page (CLP)
domain: www.aldi.us
managed_by: nimble
- name: aldi_pdp
is_public: true
display_name: Aldi Product Details Page
description: 'The Aldi Product Detail Page Agent extracts structured data from individual product pages on Aldi. This agent is ideal for tracking competitor pricing, monitoring catalog changes, and powering product intelligence use cases.
'
vertical: Ecommerce
entity_type: Product Detail Page (PDP)
domain: https://www.aldi.us/
managed_by: nimble
- name: amazon_plp
is_public: true
display_name: Amazon CLP
description: The Amazon Browse Products agent extracts structured product listings from Amazon’s category pages. This agent is ideal for monitoring category-level assortment, analyzing competitive inventory, and powering product discovery and pricing intelligence use cases
vertical: Ecommerce
entity_type: Category Landing Page (CLP)
domain: www.amazon.com
managed_by: nimble
- name: amazon_pdp
is_public: true
display_name: Amazon Product Details Page
description: The Amazon Product Detail Page Agent extracts structured data from individual product pages on Amazon. This agent is ideal for tracking competitor pricing, monitoring catalog changes, and powering product intelligence use cases.
vertical: Ecommerce
entity_type: Product Detail Page (PDP)
domain: www.amazon.com
managed_by: nimble
/v1/agents/{agent_name}:
get:
tags:
- Agents
security:
- BearerAuth: []
summary: Get Agent Details
parameters:
- name: agent_name
in: path
required: true
schema:
type: string
title: Agent Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
allOf:
- properties:
name:
type: string
title: Name
is_public:
type: boolean
title: Is Public
managed_by:
type: string
title: Managed By
display_name:
type: string
title: Display Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
vertical:
anyOf:
- type: string
- type: 'null'
title: Vertical
entity_type:
anyOf:
- type: string
- type: 'null'
title: Entity Type
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
output_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Output Schema
input_properties:
anyOf:
- items:
properties:
name:
type: string
title: Name
default: ''
required:
type: boolean
title: Required
default: false
type:
type: string
title: Type
default: string
description:
anyOf:
- type: string
- type: 'null'
title: Description
is_localization_param:
type: boolean
title: Is Localization Param
default: false
is_pagination_param:
type: boolean
title: Is Pagination Param
default: false
rules:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Rules
examples:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Examples
default:
anyOf:
- type: string
- type: 'null'
title: Default
type: object
title: AgentInputProperty
type: array
- type: 'null'
title: Input Properties
feature_flags:
properties:
is_localization_supported:
type: boolean
title: Is Localization Supported
default: false
is_pagination_supported:
type: boolean
title: Is Pagination Supported
default: false
type: object
title: FeatureFlags
type: object
required:
- name
- is_public
- display_name
title: FullAgent
examples:
- name: amazon_pdp
is_public: true
display_name: Amazon Product Details Page
description: The Amazon Product Detail Page Agent extracts structured data from individual product pages on Amazon. This agent is ideal for tracking competitor pricing, monitoring catalog changes, and powering product intelligence use cases.
vertical: Ecommerce
entity_type: Product Detail Page (PDP)
domain: www.amazon.com
managed_by: nimble
output_schema:
product_title:
type: string
description: The name of the product
manufacturer:
type: string
description: The company that manufactured the product
product_url:
type: string
description: The direct Amazon URL of the product
pack_size:
type: string
description: The packaging or pack size information (e.g., 12-pack, 500ml)
web_price:
type: number
description: The current selling price of the product in USD
product_detail_column_and_information_within_table:
type: array
description: Tabular details about the product such as specifications or attributes
items:
type: object
properties:
field:
type: string
value:
type: string
product_availability_and_delivery_terms:
type: string
description: Shipping terms, delivery times, or availability details
unit_of_measure:
type: string
description: Unit of measurement for the product (e.g., oz, lb, ml, pack)
unit_of_measure_quantity:
type: number
description: Numeric quantity of the product in the specified unit of measure
selection_for_type_of_item_field:
type: string
description: Primary selection option field label (e.g., Size, Color)
selection_for_type_of_item_field_entry:
type: string
description: The selected value for the primary selection field
secondary_selection_for_type_of_item_field:
type: string
description: Secondary selection option field label (if applicable)
secondary_selection_for_type_of_item_field_entry:
type: string
description: The selected value for the secondary selection field
list_price:
type: number
description: The original price (before discounts) of the product in USD
product_hierarchy:
type: array
description: Breadcrumb navigation path or category hierarchy for the product
items:
type: string
reviews_statistics_percentage_five_to_zero:
type: object
description: Distribution of customer ratings (5-star through 0-star)
properties:
5_star:
type: string
4_star:
type: string
3_star:
type: string
2_star:
type: string
1_star:
type: string
review_scale:
type: number
description: Numerical rating scale used (usually 5)
availability:
type: boolean
description: Whether the product is in stock (true) or out of stock (false)
image_url:
type: string
description: The URL of the product's main image
format: uri
brand:
type: string
description: The brand name of the product
product_description:
type: string
description: Detailed text description of the product
publisher:
type: string
description: The publisher, distributor, or entity responsible for listing the product
average_of_reviews:
type: number
minimum: 0
maximum: 5
description: The average customer rating (0 to 5 stars)
number_of_reviews:
type: number
description: The total number of customer reviews for the product
sold_by:
type: string
description: The entity or seller offering the product
direct:
type: boolean
description: If seller is Amazon
ships_from:
type: string
description: The fulfillment source or warehouse shipping the product
payment:
type: string
description: Available payment methods or terms
packaging:
type: string
description: Product packaging details (e.g., box, bag, recyclable packaging)
amazons_choice:
type: boolean
description: Whether the product is marked as Amazon's Choice
best_sellers_category_1_name:
type: string
description: The name of the primary Best Seller category
best_sellers_category_1_rank:
type: string
description: The Best Seller rank of the product within the primary category
best_sellers_category_2_name:
type: string
description: The name of the secondary Best Seller category
best_sellers_category_2_rank:
type: string
description: The Best Seller rank of the product within the secondary category
climate_pledge_friendly:
type: boolean
description: Indicates if the product is part of Amazon's Climate Pledge Friendly program
warning:
type: string
description: Product warnings (e.g., choking hazard, safety notes)
special_feature:
type: string
description: Unique feature or benefit of the product
variants:
type: array
description: ASINs of related or variant products (e.g., other colors or sizes)
items:
type: string
brief_product_description:
type: array
description: Bullet-point features or highlights of the product
items:
type: string
size:
type: string
description: Dimensions or size specification (LxWxH)
color:
type: string
description: Color of the product
material:
type: string
description: Material composition of the product
recommended_uses:
type: string
description: Suggested uses or scenarios for the product
model:
type: string
description: Manufacturer's model number
country_of_origin:
type: string
description: Country where the product was manufactured
asin:
type: string
description: Amazon Standard Identification Number (ASIN) of the product
customers_say:
type: string
description: AI-generated summary of customer feedback
top_reviews:
type: array
description: Top reviews for the product (typically the most helpful or recent ones)
items:
type: object
properties:
stars:
type: number
review_title:
type: string
review_body:
type: string
technical_details:
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nimbleway/refs/heads/main/openapi/nimbleway-agents-api-openapi.yml