> For the complete documentation index, see [llms.txt](https://docs.papaya.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.papaya.finance/api-1/api-reference.md).

# API Reference

## Create invoice

> Creates a new invoice with the specified rate and period for the authenticated application.

```json
{"openapi":"3.0.1","info":{"title":"Papaya Bot API","version":"v1"},"servers":[{"url":"https://bot-api.papaya.finance"}],"security":[{"X-API-Key":[]}],"components":{"securitySchemes":{"X-API-Key":{"type":"apiKey","description":"API Key needed to access the endpoints","name":"X-API-Key","in":"header"}},"schemas":{"InvoiceRequest":{"type":"object","properties":{"title":{"type":"string","nullable":true},"message":{"type":"string","nullable":true},"rate":{"type":"number","format":"double"},"period":{"$ref":"#/components/schemas/RatePeriod"},"metadata":{"type":"object","nullable":true}},"additionalProperties":false},"RatePeriod":{"enum":["PerDay","PerWeek","PerMonth","PerYear"],"type":"string"},"CreateInvoiceResponse":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"rate":{"type":"number","format":"double"},"createdAt":{"type":"string","format":"date-time"},"botUrl":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/api/invoice":{"post":{"tags":["Invoice"],"summary":"Create invoice","description":"Creates a new invoice with the specified rate and period for the authenticated application.","operationId":"CreateInvoice","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}}}},"responses":{"200":{"description":"Invoice created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceResponse"}}}},"400":{"description":"Bad request - Invalid parameters"},"401":{"description":"Unauthorized - Invalid or missing API key"},"500":{"description":"Internal server error"}}}}}}
```

## Get invoice by id

> Retrieves a specific invoice by its ID, ensuring it belongs to the authenticated application.

```json
{"openapi":"3.0.1","info":{"title":"Papaya Bot API","version":"v1"},"servers":[{"url":"https://bot-api.papaya.finance"}],"security":[{"X-API-Key":[]}],"components":{"securitySchemes":{"X-API-Key":{"type":"apiKey","description":"API Key needed to access the endpoints","name":"X-API-Key","in":"header"}},"schemas":{"InvoiceDetails":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"recipient":{"type":"string","nullable":true},"rate":{"type":"number","format":"double"},"createdAt":{"type":"string","format":"date-time"},"isPaid":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"botUrl":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/api/invoice/{id}":{"get":{"tags":["Invoice"],"summary":"Get invoice by id","description":"Retrieves a specific invoice by its ID, ensuring it belongs to the authenticated application.","operationId":"GetInvoiceById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Invoice created successfully","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/InvoiceDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetails"}}}},"400":{"description":"Bad request - Invalid parameters","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal server error"}}}}}}
```

## Get all subscriptions

> Retrieves all subscriptions for the authenticated application with pagination support.

```json
{"openapi":"3.0.1","info":{"title":"Papaya Bot API","version":"v1"},"servers":[{"url":"https://bot-api.papaya.finance"}],"security":[{"X-API-Key":[]}],"components":{"securitySchemes":{"X-API-Key":{"type":"apiKey","description":"API Key needed to access the endpoints","name":"X-API-Key","in":"header"}},"schemas":{"SubscriptionApiModelPaginatedResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionApiModel"},"description":"The items in the current page","nullable":true},"totalCount":{"type":"integer","description":"Total number of items across all pages","format":"int32"},"page":{"type":"integer","description":"Current page number (1-indexed)","format":"int32"},"limit":{"type":"integer","description":"Number of items per page","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages","format":"int32"}},"additionalProperties":false,"description":"A paginated response containing items and pagination metadata"},"SubscriptionApiModel":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the subscription","format":"int64"},"chainId":{"type":"integer","description":"Blockchain chain ID where the subscription is registered","format":"int32"},"tokenName":{"type":"string","description":"Name of the token used for the subscription payments","nullable":true},"tx":{"type":"string","description":"Transaction hash of the subscription payment","nullable":true},"tgUserId":{"type":"integer","description":"Telegram user ID associated with the subscription","format":"int64"},"userAddress":{"type":"string","description":"User's wallet address associated with the subscription","nullable":true},"createdAt":{"type":"string","description":"Creation timestamp of the subscription","format":"date-time"},"isActive":{"type":"boolean","description":"Indicates whether the subscription is currently active","format":"boolean"}},"additionalProperties":false,"description":"Subscription data model for API responses"}}},"paths":{"/api/subscriptions":{"get":{"tags":["Subscription"],"summary":"Get all subscriptions","description":"Retrieves all subscriptions for the authenticated application with pagination support.","operationId":"GetSubscriptions","parameters":[{"name":"page","in":"query","schema":{"type":"integer","format":"int32","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","format":"int32","default":50}}],"responses":{"200":{"description":"Returns paginated list of subscriptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionApiModelPaginatedResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"500":{"description":"Internal server error"}}}}}}
```

## Get subscription by ID

> Retrieves a specific subscription by its ID, ensuring it belongs to the authenticated application.

```json
{"openapi":"3.0.1","info":{"title":"Papaya Bot API","version":"v1"},"servers":[{"url":"https://bot-api.papaya.finance"}],"security":[{"X-API-Key":[]}],"components":{"securitySchemes":{"X-API-Key":{"type":"apiKey","description":"API Key needed to access the endpoints","name":"X-API-Key","in":"header"}},"schemas":{"SubscriptionApiModel":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the subscription","format":"int64"},"chainId":{"type":"integer","description":"Blockchain chain ID where the subscription is registered","format":"int32"},"tokenName":{"type":"string","description":"Name of the token used for the subscription payments","nullable":true},"tx":{"type":"string","description":"Transaction hash of the subscription payment","nullable":true},"tgUserId":{"type":"integer","description":"Telegram user ID associated with the subscription","format":"int64"},"userAddress":{"type":"string","description":"User's wallet address associated with the subscription","nullable":true},"createdAt":{"type":"string","description":"Creation timestamp of the subscription","format":"date-time"},"isActive":{"type":"boolean","description":"Indicates whether the subscription is currently active","format":"boolean"}},"additionalProperties":false,"description":"Subscription data model for API responses"}}},"paths":{"/api/subscriptions/{id}":{"get":{"tags":["Subscription"],"summary":"Get subscription by ID","description":"Retrieves a specific subscription by its ID, ensuring it belongs to the authenticated application.","operationId":"GetSubscriptionById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Returns the requested subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionApiModel"}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"404":{"description":"Subscription not found"},"500":{"description":"Internal server error"}}}}}}
```