🚫

Internal use only!

Query Parameters

The ProteusAI Management API provides a flexible pagination, filtering, and sorting system for endpoints that return collections of resources. This system is available across most collection endpoints including agents, plugins, workflows, and more.

System Parameters

All system/control parameters require the @ prefix to distinguish them from property filters:

Parameter	Type	Default	Description
`@page`	number	1	Page number for index-based pagination (min: 1)
`@limit`	number	20	Items per page (min: 1, max: 100)
`@cursor`	string	-	Cursor ID for cursor-based pagination
`@sortBy`	string/array	'createdAt'	Field(s) to sort by - supports comma-separated values
`@sortOrder`	enum/array	'desc'	Sort direction(s): `asc` or `desc` - supports comma-separated values
`@search`	string	-	Search term (implementation varies by endpoint)

Property Filters

Any query parameter without the @ prefix is treated as a property filter. The API supports:

Single values: type=EVENT_HANDLER
Comma-separated arrays: tags=integration,automation
Multiple parameters: events=CHAT_MESSAGE&events=FILE_UPLOAD

Pagination Types

Index-based Pagination

Uses page numbers and provides total count information.

Example request:

curl https://management-api.useproteus.ai/api/plugins/marketplace?@page=2&@limit=10

Response:

{
  "ok": true,
  "data": [...],
  "meta": {
    "pagination": {
      "type": "index",
      "page": 2,
      "limit": 10,
      "total": 150,
      "totalPages": 15,
      "hasNext": true,
      "hasPrev": true
    }
  }
}

Cursor-based Pagination

Uses cursor IDs for efficient pagination of large datasets.

Example request:

curl https://management-api.useproteus.ai/api/plugins/marketplace?@cursor=plugin_123&@limit=20

Response:

{
  "ok": true,
  "data": [...],
  "meta": {
    "pagination": {
      "type": "cursor",
      "limit": 20,
      "hasNext": true,
      "nextCursor": "plugin_456"
    }
  }
}

Filtering

Search Filtering

The @search parameter performs text search across designated fields (implementation-specific):

curl https://management-api.useproteus.ai/api/plugins/marketplace?@search=email

Property Filtering

Property filters are applied dynamically based on the parameter name:

curl https://management-api.useproteus.ai/api/plugins/marketplace?tags=integration,automation&type=EVENT_HANDLER&orgId=123

Filter Processing

The API automatically handles different data types:

Array properties (tags, events, scopes): Uses hasSome operator
Regular arrays: Uses in operator for multiple values
Single values: Uses direct equality

Examples

Query Parameter	Processed Value	Database Query
`type=EVENT_HANDLER`	`"EVENT_HANDLER"`	`{ type: "EVENT_HANDLER" }`
`tags=ai,automation`	`["ai", "automation"]`	`{ tags: { hasSome: ["ai", "automation"] } }`
`orgId=123,456`	`["123", "456"]`	`{ orgId: { in: ["123", "456"] } }`

Sorting

Sorting is controlled by @sortBy and @sortOrder parameters.

Single Field Sorting

curl https://management-api.useproteus.ai/api/plugins/marketplace?@sortBy=name&@sortOrder=asc

Multi-Field Sorting

Sort by multiple fields using comma-separated values:

curl https://management-api.useproteus.ai/api/plugins/marketplace?@sortBy=name,createdAt&@sortOrder=asc,desc

If fewer sort orders are provided than sort fields, the last provided order is used for remaining fields. For example: @sortBy=name,createdAt,type&@sortOrder=asc sorts as name: asc, createdAt: asc, type: asc

Usage Examples

Basic Pagination

# Get first page with 10 items
curl https://management-api.useproteus.ai/api/plugins/marketplace?@page=1&@limit=10
 
# Get second page
curl https://management-api.useproteus.ai/api/plugins/marketplace?@page=2&@limit=10

Filtering and Sorting

# Search for "slack" plugins, filter by type, sort by name
curl https://management-api.useproteus.ai/api/plugins/marketplace?@search=slack&type=EVENT_HANDLER&@sortBy=name&@sortOrder=asc
 
# Filter by multiple tags
curl https://management-api.useproteus.ai/api/plugins/marketplace?tags=chat,messaging,automation
 
# Multi-field sorting with filtering
curl https://management-api.useproteus.ai/api/plugins/marketplace?tags=integration&@sortBy=name,createdAt&@sortOrder=asc,desc
 
# Complex filtering with multi-field sorting
curl https://management-api.useproteus.ai/api/plugins/marketplace?@search=email&tags=integration&type=EVENT_HANDLER&orgId=123&@sortBy=createdAt,name&@sortOrder=desc,asc

Cursor-based Pagination

# First request
curl https://management-api.useproteus.ai/api/plugins/marketplace?@limit=20
 
# Subsequent requests using returned cursor
curl https://management-api.useproteus.ai/api/plugins/marketplace?@cursor=plugin_abc123&@limit=20

Response Format

All paginated endpoints return a consistent response structure:

{
  "ok": true,
  "data": [...],
  "meta": {
    "pagination": {
      // Pagination metadata (varies by type)
    }
  }
}

Error Handling

The API provides detailed error responses for invalid parameters:

{
  "ok": false,
  "error": {
    "message": "Invalid query parameters",
    "details": [
      {
        "code": "invalid_type",
        "expected": "number",
        "received": "string",
        "path": ["@limit"],
        "message": "Expected number, received string"
      }
    ]
  }
}

Best Practices

Use cursor-based pagination for large datasets or real-time feeds
Use index-based pagination when users need page numbers or total counts
Implement search for better user experience on text-heavy resources
Combine filters to narrow down results efficiently
Use multi-field sorting for predictable result ordering

Object Reference Tokens