# 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"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.papaya.finance/api-1/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.