> ## Documentation Index > Fetch the complete documentation index at: https://docs.sub.jerrylu.app/llms.txt > Use this file to discover all available pages before exploring further. # List subscriptions > Returns subscriptions owned by the authenticated API key owner, newest first. Use the limit and offset query parameters to page through results. ## OpenAPI ````yaml /api/openapi.yaml get /api/v1/subscriptions openapi: 3.1.0 info: title: Subscription Manager Public API version: 1.0.0 description: >- Public API for subscription CRUD automation through Developer API keys. The operation descriptions include AI-oriented task semantics, risk levels, and confirmation guidance for agent integrations. servers: - url: https://your-site.example description: Replace with your deployed Subscription Manager site URL. security: - bearerApiKey: [] tags: - name: Subscriptions description: Create, read, update, and delete subscriptions for the API key owner. x-ai: domain: subscription_management ownerScope: authenticated_api_key_owner writeSafety: >- Confirm create, update, cancel, pause, resume, and delete operations with the user before calling them from an AI agent. Write operations require an API key with the write scope. - name: Analytics description: >- Computed spend summaries, duplicate detection, and optimization candidates. Read-only; money is reported per currency and never converted. - name: Audit description: Read-only audit trail of write operations performed through the API. paths: /api/v1/subscriptions: get: tags: - Subscriptions summary: List subscriptions description: >- Returns subscriptions owned by the authenticated API key owner, newest first. Use the limit and offset query parameters to page through results. operationId: listSubscriptions parameters: - name: limit in: query required: false description: Maximum number of subscriptions to return (1-100, default 50). schema: type: integer minimum: 1 maximum: 100 default: 50 - name: offset in: query required: false description: >- Number of subscriptions to skip from the start of the list (default 0). schema: type: integer minimum: 0 default: 0 - name: status in: query required: false description: Filter by lifecycle state. schema: $ref: '#/components/schemas/SubscriptionStatus' - name: category in: query required: false description: Exact category match, for example "Streaming". schema: type: string - name: period in: query required: false description: Filter by billing period. schema: $ref: '#/components/schemas/SubscriptionPeriod' - name: q in: query required: false description: Case-insensitive search over the subscription name. schema: type: string - name: expiringBefore in: query required: false description: >- Return subscriptions whose nextPaymentDate is on or before this date. Combine with status=active to find renewals due soon. schema: $ref: '#/components/schemas/DateOnly' - name: sort in: query required: false description: >- Sort order; prefix with - for descending, for example -nextPaymentDate. schema: type: string default: '-createdAt' enum: - createdAt - '-createdAt' - nextPaymentDate - '-nextPaymentDate' - amount - '-amount' - name - '-name' responses: '200': description: Subscriptions returned. headers: X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/SubscriptionListResponse' examples: subscriptions: value: data: - id: 33333333-3333-4333-8333-333333333333 name: Netflix category: Streaming amount: 15.99 currency: USD period: monthly lastPaymentDate: '2026-06-01' nextPaymentDate: '2026-07-01' notificationEnabled: true status: active createdAt: '2026-06-16T00:00:00.000Z' updatedAt: '2026-06-16T00:00:00.000Z' pagination: limit: 50 offset: 0 hasMore: false query: sort: '-createdAt' filters: {} requestId: request-1 '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: SubscriptionStatus: type: string description: >- Lifecycle state. active means billing; paused means temporarily stopped; cancelled means no longer billing but kept for history. enum: - active - paused - cancelled SubscriptionPeriod: type: string description: Billing cadence used to calculate nextPaymentDate. enum: - monthly - yearly - custom DateOnly: type: string description: Calendar date without time, always in YYYY-MM-DD format. pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-06-01' SubscriptionListResponse: type: object required: - data - pagination - requestId properties: data: type: array items: $ref: '#/components/schemas/Subscription' pagination: $ref: '#/components/schemas/Pagination' query: type: object description: Echo of the sort and filters applied to this response. properties: sort: type: string filters: type: object additionalProperties: true additionalProperties: false requestId: type: string additionalProperties: false Subscription: type: object required: - id - name - category - amount - currency - period - lastPaymentDate - nextPaymentDate - notificationEnabled - status - createdAt - updatedAt properties: id: type: string format: uuid description: Server-generated subscription identifier. name: type: string description: Human-readable service or product name. minLength: 1 maxLength: 120 category: type: string description: User-visible category label used for grouping and analytics. minLength: 1 maxLength: 80 amount: type: number description: >- Payment amount in major currency units, with at most 2 decimal places. minimum: 0 maximum: 999999.99 multipleOf: 0.01 currency: $ref: '#/components/schemas/Currency' period: $ref: '#/components/schemas/SubscriptionPeriod' lastPaymentDate: $ref: '#/components/schemas/DateOnly' nextPaymentDate: $ref: '#/components/schemas/DateOnly' description: Server-calculated next payment date. customDate: type: string pattern: ^[1-9]\d*$ description: >- Required only when period is custom. Despite the legacy name, this is a positive whole-number string of days, not a calendar date. notificationEnabled: type: boolean status: $ref: '#/components/schemas/SubscriptionStatus' createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false Pagination: type: object required: - limit - offset - hasMore properties: limit: type: integer minimum: 1 maximum: 100 description: Page size that was applied to this response. offset: type: integer minimum: 0 description: Number of records skipped before this page. hasMore: type: boolean description: >- True when at least one more record exists past this page. Fetch the next page with offset + limit. additionalProperties: false ErrorResponse: type: object required: - error - requestId properties: error: $ref: '#/components/schemas/Error' requestId: type: string additionalProperties: false Currency: type: string description: ISO-like currency code supported by the app. enum: - CNY - USD - EUR - JPY - GBP - AUD - CAD - CHF - HKD - SGD Error: type: object required: - code - message properties: code: type: string message: type: string field: type: string description: Field that caused the error when the server can identify one. suggestedFix: type: string description: Human- and AI-readable correction hint. allowedValues: type: array items: type: string description: Allowed enum values when the error is caused by an unsupported enum. writableFields: type: array items: type: string description: >- Writable subscription fields when the error is caused by a non-writable field. additionalProperties: false headers: XRateLimitLimit: description: Total allowed requests in the current fixed window. schema: type: integer example: 60 XRateLimitRemaining: description: Requests remaining in the current fixed window. schema: type: integer example: 59 XRateLimitReset: description: Unix timestamp in seconds when the fixed window resets. schema: type: integer example: 1781690400 RetryAfter: description: >- Seconds to wait before retrying. Sent with 429 responses, including when too many invalid API key attempts are throttled. schema: type: integer example: 2700 responses: Unauthorized: description: The API key is missing, invalid, or revoked. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidApiKey: value: error: code: invalid_api_key message: Invalid API key requestId: request-1 RateLimited: description: The user request limit or invalid-auth attempt limit was exceeded. headers: X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: value: error: code: rate_limit_exceeded message: Rate limit exceeded requestId: request-1 tooManyInvalidKeys: value: error: code: rate_limit_exceeded message: Too many invalid API key attempts requestId: request-1 InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal: value: error: code: internal_error message: Internal server error requestId: request-1 securitySchemes: bearerApiKey: type: http scheme: bearer description: >- Developer API key generated in the app. Keys carry scopes; a read key can call list, get, analytics, and audit endpoints, while a write key additionally allows create, update, cancel, pause, resume, and delete. x-default: subm_your_key_here ````