> ## Documentation Index > Fetch the complete documentation index at: https://docs.solya.app/llms.txt > Use this file to discover all available pages before exploring further. # Get tasks including AI-generated per-product action recommendations > Returns a paginated, enriched list of tasks for the organization. Optional filters narrow by status, source type, assignee, shop, variant, or domain. Filter by sourceType=ACTION_VECTOR to retrieve AI-generated restock, rebalance, and markdown recommendations with embedded decisionVectorSnapshot scores — these are the per-product, per-shop action items produced by the AI recommendation engine. ACTION_VECTOR tasks carry a PRODUCT_ACTION enrichment block with recommendedQty, recommendedDiscount, confidence, and the full decisionVectorSnapshot captured at emit time. Enrichment adds source-specific display data (alert name, plan name, product labels) and structured scopes (shop/brand) resolved at read time. ## OpenAPI ````yaml /openapi.json get /api/tasks openapi: 3.0.3 info: contact: email: dev@solya.io name: Solya Team description: >- # Solya API Solya is a fashion retail inventory management platform for buyers and merchandisers. This API exposes all capabilities needed to manage the inventory lifecycle: catalog browsing, risk detection, plan creation (Restock / Markdown / Rebalance), analytics queries, and data-platform operations. ## Authentication Three authentication schemes are supported: | Scheme | Header | Use case | |---|---|---| | **BearerAuth** | `Authorization: Bearer ` | Human users via the Solya web app (NextAuth session) | | **InternalBearerAuth** | `Authorization: Bearer ` | Internal jobs and cron tasks (static token per service) | | **ServiceAccountToken** | `Authorization: Bearer solya_sa_*` | LLM agents and programmatic clients (opaque token created via Settings) | All endpoints except `GET /api/health` require one of the above. See [Agent authentication guide](/docs/api/AGENT_AUTH.md) for the Service Account token flow. ## Response format Every endpoint returns an `ActionResponse` envelope: **Success:** ```json { "success": true, "data": { ... } } ``` **Error:** ```json { "success": false, "errorCode": "PLAN_NOT_FOUND", "error": "Human-readable message" } ``` The `errorCode` is a stable machine-readable string (see common error codes below). The `error` field is for human display only and may change between versions. ## Pagination List endpoints accept `page` (1-indexed, default 1) and `pageSize` (default 20, max 100). Responses include a `total` field with the total number of matching records. ``` GET /api/shops?page=2&pageSize=50 → { "success": true, "data": { "data": [...], "total": 120, "page": 2, "pageSize": 50 } } ``` ## Common error codes | HTTP status | errorCode | Meaning | |---|---|---| | 401 | `UNAUTHORIZED` | Token missing, expired, or invalid | | 403 | `FORBIDDEN` | Token valid but lacks the required permission or scope | | 404 | `NOT_FOUND` | Requested resource does not exist | | 409 | `BUSINESS_RULE_VIOLATION` | Business rule blocked the operation (see response details) | | 422 | `VALIDATION_ERROR` | Input failed Zod schema validation | | 429 | `RATE_LIMIT_EXCEEDED` | Rate limit hit (100 req/min per token) | | 500 | `INTERNAL_ERROR` | Unexpected server error | ## Rate limiting Default limit: **100 requests per minute** per authentication token. When the limit is exceeded the API returns HTTP 429 with `errorCode: "RATE_LIMIT_EXCEEDED"`. Agents should implement exponential back-off and respect the `Retry-After` header when present. ## Further reading See the [Agent guide](/docs/api/AGENT_GUIDE.md) for end-to-end workflows, call-chaining patterns, and anti-patterns to avoid. license: name: Proprietary url: https://solya.app/terms title: Solya API version: 1.0.0 x-ai-context: >- Solya is a fashion retail inventory management platform for retailers. Core concepts: - **Organization** (tenant): every endpoint is scoped by organizationId extracted from the token. - **Shop**: a physical point of sale belonging to the organization. - **ProductVariant**: a SKU — a product variant with size and color. - **Plan**: a Restock / Markdown / Rebalance grouping PlanItems to orchestrate inventory decisions. Typical agent workflow: 1. List the organization's shops — GET /api/shops 2. List variants at risk (stockout, overstock, slow-mover) — GET /api/inventory/risks 3. Create a plan — POST /api/restock-plans, /api/markdown-plans, or /api/rebalance-plans 4. Add items to the plan — POST /api/restock-plans/{planId}/items (or equivalent for other plan types) 5. Validate / submit the plan via the corresponding action endpoint Auth: use a Service Account token (see /docs/api/AGENT_AUTH.md). The token is created by an org admin via Settings and has the format solya_sa_<43 base64url chars>. All responses follow the ActionResponse envelope: - Success: { success: true, data: T } - Error: { success: false, errorCode: string, error: string } Use the errorCode field to drive retry logic or surface user-facing messages. servers: - description: Current environment url: https://app.solya.app security: - BearerAuth: [] tags: - description: >- Health and liveness endpoints. Use GET /api/health to verify the service is reachable before starting a workflow. No authentication required. name: System - description: >- Physical points of sale belonging to the organization. Supports listing, creation, update, and deactivation. Shops are referenced by all Plan types (Restock, Markdown, Rebalance) and by every inventory analytics endpoint. name: Shops - description: >- Product brands configured for the organization. Brands are used to filter catalog queries and analytics. Supports CRUD operations. name: Brands - description: >- The product catalog: style-level entities grouping one or more ProductVariants. Supports listing with rich filter options (brand, family, gender, season) and individual retrieval. name: Products - description: >- SKU-level product entities (a Product with a specific size and color). Variants are the atomic unit referenced by PlanItems, inventory risk alerts, and analytics queries. name: Variants - description: >- Curated product groupings used for seasonal assortment management. A Collection groups Variants and can be referenced when creating or filtering Plans. name: Collections - description: >- Current on-hand stock records per Variant per Shop. Used to understand the live inventory position before creating a restock or rebalance plan. name: Inventory Items - description: >- AI-detected inventory risk signals: stockout risk, overstock, slow-movers, and displaced stock. The primary input for agents building recommendation-driven plans. Supports filtering by shop, brand, risk type, and severity. name: Inventory Risks - description: >- AI-generated restock quantity recommendations per Variant per Shop. Consumed by agents to pre-populate Restock plan items. Based on sales velocity, stock coverage, and lead time. name: Recommendations - Restock - description: >- AI-generated markdown discount recommendations for slow-moving or overstock Variants. Consumed by agents to pre-populate Markdown plan items. Includes recommended discount rate and expected clearance timeline. name: Recommendations - Markdown - description: >- AI-generated stock transfer recommendations between shops to balance supply with demand. Consumed by agents to pre-populate Rebalance plan items. name: Recommendations - Rebalance - description: >- Historical sales transaction lines at the Variant + Shop + date level. Used by analytics and by the AI recommendation engine. Supports date-range and multi-dimensional filtering. name: Sales Lines - description: >- Purchase order lines tracking inbound stock from suppliers. Combined with stock and sales data to compute forward coverage and restock needs. name: Order Lines - description: >- Inventory movement records (transfers, returns, adjustments). Used to reconcile the stock ledger and audit stock changes between shops. name: Movement Lines - description: >- Running stock balance log per Variant per Shop. Provides a point-in-time view of stock levels and is the source of truth for coverage computations. name: Stock Ledger - description: >- Rebalance plans orchestrate stock transfers between shops. Supports creating plans, adding Variant items with proposed transfer quantities, reviewing, and submitting. Business rules are evaluated on item addition. name: Plans - Rebalance - description: >- Restock plans (order plans) orchestrate purchase orders to suppliers. Supports creating sessions, adding Variant items with proposed order quantities, reviewing totals, and submitting. Integrates with the order plan workflow. name: Plans - Restock - description: >- Autocomplete and typeahead search endpoints for catalog dimensions: products, brands, shops, sizes, families, genders, and more. Designed for fast UI search (low latency, small result sets). Use catalog list endpoints for full paginated access. name: Search - description: >- Manage file-based data ingestion: upload CSV/XLSX files, poll ingestion status, list historical ingestion runs, and trigger batch reprocessing. Used by the data team to import POS data and catalog updates. name: Data Platform - File Ingestions - description: >- Organization-level configuration for the data platform: data source connections, POS integration settings, and ingestion schedules. Requires elevated permissions. name: Data Platform - Settings - description: >- Configuration of automated inventory alerts: threshold-based rules that monitor stock levels, sales velocity, and coverage gaps. Supports CRUD for alert definitions; alert evaluation runs are triggered by the data platform scheduler. name: Data Platform - Alerts - description: >- Endpoints designed for LLM agents and programmatic clients. These endpoints expose agent-optimized response shapes. Authenticate with a Service Account token (format: solya_sa_*) created via Settings → API Tokens. name: Agent externalDocs: description: >- Complete guide for LLM agents and programmatic clients: authentication, pagination patterns, ActionResponse interpretation, call chaining, business rule error handling. url: /docs/api/AGENT_GUIDE.md paths: /api/tasks: get: tags: - Tasks summary: Get tasks including AI-generated per-product action recommendations description: >- Returns a paginated, enriched list of tasks for the organization. Optional filters narrow by status, source type, assignee, shop, variant, or domain. Filter by sourceType=ACTION_VECTOR to retrieve AI-generated restock, rebalance, and markdown recommendations with embedded decisionVectorSnapshot scores — these are the per-product, per-shop action items produced by the AI recommendation engine. ACTION_VECTOR tasks carry a PRODUCT_ACTION enrichment block with recommendedQty, recommendedDiscount, confidence, and the full decisionVectorSnapshot captured at emit time. Enrichment adds source-specific display data (alert name, plan name, product labels) and structured scopes (shop/brand) resolved at read time. operationId: listTasks parameters: - in: query name: page required: false schema: default: 1 description: 'Page number, 1-indexed (default: 1)' maximum: 9007199254740991 minimum: 1 type: integer - in: query name: pageSize required: false schema: default: 20 description: 'Number of items per page, max 100 (default: 20)' maximum: 100 minimum: 1 type: integer - in: query name: status required: false schema: anyOf: - enum: - OPEN - IN_PROGRESS - DONE - DISMISSED type: string - items: enum: - OPEN - IN_PROGRESS - DONE - DISMISSED type: string type: array description: >- Filter by one or more task statuses (comma-separated or array). Allowed values: OPEN, IN_PROGRESS, DONE, DISMISSED. - in: query name: sourceType required: false schema: anyOf: - enum: - ACTION_APPROVAL - PLAN_APPROVAL - ALERT_INSTANCE - RECOMMENDED_PLAN - ACTION_VECTOR type: string - items: enum: - ACTION_APPROVAL - PLAN_APPROVAL - ALERT_INSTANCE - RECOMMENDED_PLAN - ACTION_VECTOR type: string type: array description: >- Filter by one or more task source types (comma-separated or array). Allowed values: PLAN_APPROVAL, ALERT_INSTANCE, RECOMMENDED_PLAN, ACTION_VECTOR. - in: query name: assigneeId required: false schema: description: >- Filter tasks by assignee user ID. Returns only tasks assigned to this user. type: string - in: query name: domain required: false schema: description: >- Filter PRODUCT_ACTION tasks by decision domain. Allowed values: restock, rebalance, markdown. enum: - restock - rebalance - markdown type: string - in: query name: shopId required: false schema: description: >- Filter tasks by shop ID. Returns only PRODUCT_ACTION tasks linked to this shop. type: string - in: query name: variantId required: false schema: description: >- Filter tasks by variant ID. Returns only PRODUCT_ACTION tasks linked to this variant. type: string - in: query name: sortBy required: false schema: description: >- Field to sort results by. Defaults to createdAt. Allowed values: createdAt, updatedAt, priority, dueDate. enum: - createdAt - updatedAt - priority - dueDate type: string - in: query name: sortOrder required: false schema: description: 'Sort direction. Defaults to desc. Allowed values: asc, desc.' enum: - asc - desc type: string responses: '200': content: application/json: examples: sample: summary: Two tasks on the first page value: data: - assigneeId: 550e8400-e29b-41d4-a716-446655440030 category: APPROVAL createdAt: '2026-06-01T08:00:00.000Z' domain: null dueDate: '2026-07-01T00:00:00.000Z' enrichment: actualValue: 12500 kind: PLAN_APPROVAL planName: Rebalance Summer 2026 planType: REBALANCE status: PENDING thresholdValue: 10000 evidence: null id: 550e8400-e29b-41d4-a716-446655440001 kind: null organizationId: 550e8400-e29b-41d4-a716-446655440010 payload: null priority: HIGH scopes: [] shopId: null sourceId: 550e8400-e29b-41d4-a716-446655440020 sourceType: PLAN_APPROVAL status: OPEN updatedAt: '2026-06-01T08:00:00.000Z' variantId: null workflowRunId: null - assigneeId: null category: ALERT createdAt: '2026-06-03T10:00:00.000Z' domain: null dueDate: null enrichment: alertName: Low stock alert description: null kind: ALERT_INSTANCE scopeLabels: - Nike - Paris Store tagNames: [] tagOperator: AND tagRules: [] triggeredValue: 3 evidence: null id: 550e8400-e29b-41d4-a716-446655440002 kind: REVIEW organizationId: 550e8400-e29b-41d4-a716-446655440010 payload: null priority: URGENT scopes: - id: shop-paris kind: SHOP label: Paris Store shopId: null sourceId: 550e8400-e29b-41d4-a716-446655440021 sourceType: ALERT_INSTANCE status: IN_PROGRESS updatedAt: '2026-06-03T14:00:00.000Z' variantId: null workflowRunId: null meta: page: 1 pageSize: 20 total: 11 schema: properties: data: description: Page of items items: properties: assigneeId: description: >- ID of the user this task is assigned to, or null if unassigned. nullable: true type: string category: description: >- Coarse UI grouping bucket: APPROVAL, ALERT, or RECOMMENDATION. type: string createdAt: description: ISO 8601 timestamp when the task was created. type: string domain: description: >- Decision domain for PRODUCT_ACTION todos (restock/rebalance/markdown); null for other types. nullable: true type: string dueDate: description: ISO 8601 due date, or null if no due date is set. nullable: true type: string enrichment: description: >- Source-specific enrichment data resolved at read time; null when none applies. nullable: true oneOf: - properties: alertName: description: >- Human-readable alert name from the parent alert definition. type: string description: description: >- Stored alert description, or null when not set. nullable: true type: string kind: description: Enrichment kind discriminator. enum: - ALERT_INSTANCE type: string scopeLabels: description: >- Combined short list of brand and shop names from the alert scope (capped at 3 entries). items: type: string type: array tagNames: description: >- Display names for the tags referenced in tagRules. items: properties: id: description: Tag ID. type: string name: description: Tag display name. type: string required: - id - name type: object type: array tagOperator: description: >- Logical operator combining tag rules ('AND' or 'OR'). type: string tagRules: description: >- Tag rules used to construct the generated description. items: properties: mode: description: Tag rule mode. type: string tagId: description: Tag identifier. type: string required: - tagId - mode type: object type: array triggeredValue: description: >- The metric value that triggered the alert instance, or null. nullable: true type: number required: - kind - alertName - scopeLabels - triggeredValue - description - tagRules - tagNames - tagOperator type: object - properties: actualValue: description: The actual metric value at request time. type: number kind: description: Enrichment kind discriminator. enum: - PLAN_APPROVAL type: string planName: description: >- Human-readable plan name, or null when the plan no longer exists. nullable: true type: string planType: description: Plan type (e.g. REBALANCE, MARKDOWN). type: string status: description: >- Current approval status (e.g. PENDING, APPROVED). type: string thresholdValue: description: >- The threshold value that triggered the approval request. type: number required: - kind - planName - planType - thresholdValue - actualValue - status type: object - properties: kind: description: Enrichment kind discriminator. enum: - RECOMMENDED_PLAN type: string planName: description: >- Human-readable plan name, or null when the plan no longer exists. nullable: true type: string planType: description: Plan type (e.g. RESTOCK, REBALANCE). type: string required: - kind - planName - planType type: object - properties: confidence: description: >- Confidence in [0, 1] from the decision-vector snapshot; null when absent. nullable: true type: number decisionVectorSnapshot: additionalProperties: {} description: >- Full decision-vector snapshot captured at materializer emit time. nullable: true type: object domain: description: >- Decision domain: restock | rebalance | markdown. type: string evidence: description: Justifying signals — empty array when none. items: properties: label: description: >- Human-readable label explaining why this todo was generated. type: string signalId: description: ID of the originating signal entity. type: string signalType: description: >- Discriminator for the signal category (e.g. 'ALERT', 'DECISION_VECTOR'). type: string required: - signalType - signalId - label type: object type: array kind: description: Enrichment kind discriminator. enum: - PRODUCT_ACTION type: string productId: description: >- Product ID resolved from the variant; null when unresolvable. nullable: true type: string productLabel: description: >- Resolved product display name; null when unresolvable. nullable: true type: string recommendedDiscount: description: >- Recommended markdown discount percentage; null for non-markdown todos. nullable: true type: number recommendedQty: description: >- Recommended quantity for restock/rebalance todos; null for markdown. nullable: true type: number shopId: description: Shop ID from the task row. type: string shopLabel: description: >- Resolved shop display name; falls back to shopId. type: string targetPlanId: description: >- Target plan this todo feeds once applied; null until linked. nullable: true type: string todoKind: description: >- Row-level kind from the task (PRODUCT_ACTION or REVIEW). type: string variantId: description: Variant ID from the task row. type: string variantLabel: description: >- Resolved variant display name; falls back to variantId. type: string required: - kind - todoKind - domain - recommendedQty - recommendedDiscount - confidence - decisionVectorSnapshot - evidence - targetPlanId - variantId - shopId - productId - variantLabel - productLabel - shopLabel type: object evidence: description: >- Justifying signals for PRODUCT_ACTION todos; null for other task types. items: properties: label: description: >- Human-readable label explaining why this todo was generated. type: string signalId: description: ID of the originating signal entity. type: string signalType: description: >- Discriminator for the signal category (e.g. 'ALERT', 'DECISION_VECTOR'). type: string required: - signalType - signalId - label type: object nullable: true type: array id: description: Unique identifier of the task (UUID). type: string kind: description: >- Row-level discriminator: PRODUCT_ACTION, REVIEW, or APPROVAL. Null for legacy tasks. nullable: true type: string organizationId: description: Organization that owns this task. type: string payload: additionalProperties: {} description: >- Source-specific payload; type-specific optional data for certain task types. nullable: true type: object priority: description: 'Priority level: LOW, MEDIUM, HIGH, or URGENT.' enum: - LOW - MEDIUM - HIGH - URGENT type: string scopes: description: >- Structured shop/brand scopes the task concerns, resolved at read time. items: properties: id: description: >- Stable shop/brand identifier used as the group key. type: string kind: description: 'Scope axis: SHOP or BRAND.' type: string label: description: >- Human-readable shop/brand name; falls back to id when unresolved. type: string required: - kind - id - label type: object type: array shopId: description: >- Shop ID for PRODUCT_ACTION todos; null for other task types. nullable: true type: string sourceId: description: >- ID of the source entity (approval ID, alert instance ID, plan ID, etc.). type: string sourceType: description: >- Discriminator for the entity that created this task: PLAN_APPROVAL, ALERT_INSTANCE, RECOMMENDED_PLAN, or ACTION_VECTOR. enum: - ACTION_APPROVAL - PLAN_APPROVAL - ALERT_INSTANCE - RECOMMENDED_PLAN - ACTION_VECTOR type: string status: description: >- Lifecycle status of the task: OPEN, IN_PROGRESS, DONE, or DISMISSED. enum: - OPEN - IN_PROGRESS - DONE - DISMISSED type: string updatedAt: description: ISO 8601 timestamp of the last update to the task. type: string variantId: description: >- Variant ID for PRODUCT_ACTION todos; null for other task types. nullable: true type: string workflowRunId: description: >- Databricks workflow run ID that created this task, or null for cron-sweep / manual tasks. nullable: true type: string required: - id - organizationId - sourceType - sourceId - status - assigneeId - priority - dueDate - category - kind - variantId - shopId - domain - payload - evidence - workflowRunId - createdAt - updatedAt - enrichment type: object type: array meta: description: Pagination metadata properties: page: description: Current page number (1-indexed) type: number pageSize: description: Number of items per page type: number total: description: Total number of items matching the filters type: number required: - total - page - pageSize type: object success: enum: - true type: boolean required: - success - data - meta type: object description: Successful response '400': description: Validation error '401': description: Unauthorized '500': description: Internal server error security: - BearerAuth: [] components: securitySchemes: BearerAuth: bearerFormat: JWT description: >- User session token issued by NextAuth. For human users accessing Solya via the web application. scheme: bearer type: http ````