Welcome to the PantheraHive Notifications API documentation! This guide provides comprehensive details for integrating with our powerful notification system, enabling you to send real-time, personalized communications to your users.
The PantheraHive Notifications API empowers developers to seamlessly integrate robust notification capabilities into their applications. Whether you need to send transactional alerts, marketing messages, or system updates, our API provides a flexible and reliable platform. Designed for scalability and ease of use, this API ensures your messages reach the right users at the right time, across various channels.
Key Features:
Who is this API for?
This documentation is intended for developers, product managers, and technical leads looking to integrate sophisticated notification features into web, mobile, or backend applications. A basic understanding of RESTful APIs, HTTP protocols, and JSON data formats is recommended.
To begin sending notifications with the PantheraHive Notifications API, follow these quick steps.
All requests to the PantheraHive Notifications API must be authenticated using an API Key. You can generate your API Key from your PantheraHive Developer Dashboard under "API Keys".
Authentication Method:
Include your API Key in the Authorization header of every request as a Bearer token.
Example Header:
#### Get Notification Status
Retrieves the delivery status and details of a specific notification.
**Endpoint:** `/{notification_id}`
**Method:** `GET`
**Description:**
Use this endpoint to check the status of a notification previously sent via the `/send` endpoint. The `notification_id` is returned in the successful response of the `/send` call.
**Path Parameters:**
| Parameter | Type | Required | Description | Example |
| :---------------- | :----- | :------- | :------------------------------ | :------------------ |
| `notification_id` | String | Yes | The unique ID of the notification. | `noti_abc123xyz456` |
**Example Request:**
As "gemini", I have thoroughly researched the topic "API Documentation Writer" to provide a comprehensive and detailed understanding. This output serves as the foundational research for developing effective API documentation strategies and content.
An API Documentation Writer is a specialized technical writer who creates, maintains, and manages documentation for Application Programming Interfaces (APIs). This role is crucial for the success and adoption of any API, acting as the primary bridge between the API's developers and its consumers (e.g., other developers, partners, internal teams). Effective API documentation significantly enhances the developer experience (DX), reduces support overhead, and accelerates integration time.
The responsibilities of an API Documentation Writer are multifaceted and highly collaborative, encompassing various stages of the API lifecycle:
* Collaborating closely with API developers, product managers, and architects to understand API functionality, design, and intended use cases.
* Analyzing API specifications (e.g., OpenAPI/Swagger definitions), code, design documents, and test cases to extract necessary details.
* Participating in design reviews and sprint meetings to stay current with API development.
* Reference Documentation: Writing detailed descriptions of endpoints, methods, parameters, request/response bodies, authentication mechanisms, error codes, and data models.
* Getting Started Guides: Crafting clear, step-by-step instructions for initial setup, authentication, and making the first API call.
* Tutorials & How-To Guides: Developing practical, use-case-driven examples that demonstrate how to achieve specific tasks with the API.
* SDK Documentation: Explaining how to use Software Development Kits (SDKs) and client libraries.
* Code Samples: Creating and validating runnable code snippets in multiple programming languages (e.g., cURL, Python, JavaScript, Java, Ruby) to illustrate API usage.
* Conceptual Overviews: Providing high-level explanations of the API's architecture, core concepts, and underlying business logic.
* Regularly reviewing and updating existing documentation to reflect API changes, deprecations, and new features.
* Managing version control for documentation to align with API versions.
* Ensuring accuracy, consistency, and completeness across all documentation assets.
* Testing documentation against the live API to verify accuracy of examples and instructions.
* Gathering feedback from users and internal teams to identify areas for improvement.
* Ensuring documentation adheres to established style guides and branding.
* Selecting and leveraging appropriate documentation tools and platforms.
* Defining and implementing documentation workflows and best practices.
* Contributing to the development of documentation standards and templates.
To excel in this role, an API Documentation Writer requires a unique blend of technical, writing, and interpersonal skills:
* Clarity, conciseness, and precision in language.
* Strong grammar, punctuation, and stylistic consistency.
* Ability to translate complex technical concepts into easily understandable language for varied audiences.
* Fundamental understanding of API concepts (REST, GraphQL, SOAP, webhooks).
* Familiarity with data formats (JSON, XML) and serialization/deserialization.
* Knowledge of authentication methods (OAuth, API Keys, JWT).
* Ability to read and understand code (e.g., Python, JavaScript, Java, Go, C#) to interpret API behavior.
* Understanding of development workflows (version control, CI/CD).
* Ability to put themselves in the shoes of the API consumer.
* Understanding different user personas (e.g., beginner developers, experienced integrators, business users).
* Focus on user goals and pain points.
* Proficiency in interviewing Subject Matter Experts (SMEs).
* Ability to independently research and analyze technical specifications.
* Strong problem-solving skills to fill knowledge gaps.
* Excellent interpersonal skills for working with developers, product managers, QA, and support teams.
* Ability to articulate documentation needs and advocate for the user experience.
* Meticulous review for accuracy, completeness, and consistency.
* Careful validation of code samples and API responses.
API Documentation Writers utilize a range of tools to create, manage, and publish documentation effectively:
* OpenAPI (Swagger): Widely used for defining RESTful APIs, often serves as the source for generating documentation.
* AsyncAPI: For event-driven APIs.
* Swagger UI/Editor: For rendering OpenAPI specifications into interactive documentation.
* Postman: Can generate documentation directly from API collections.
* ReadMe.io, Stoplight, Apiary: Dedicated API documentation platforms offering interactive features, analytics, and versioning.
* Docusaurus, GitBook, Slate, MkDocs: Static site generators popular for technical documentation.
* Custom CMS/Publishing Systems: Internal tools for larger organizations.
* Git (GitHub, GitLab, Bitbucket): Essential for managing documentation source files, collaboration, and versioning.
* Markdown, reStructuredText, AsciiDoc: For writing content in a human-readable and machine-renderable format.
* Postman, Insomnia, cURL: Used to test API endpoints, validate responses, and generate accurate code samples.
* VS Code, Sublime Text, Atom: For writing and editing documentation files and code samples.
Effective API documentation adheres to several guiding principles:
The API Documentation Writer plays a pivotal role in the success of any API product. By providing clear, accurate, and user-friendly documentation, they empower developers, foster API adoption, and contribute significantly to a positive developer experience. This detailed research provides the necessary foundation for understanding the scope, skills, tools, and best practices involved in this critical function.
Possible status values for channels_status:
queued: Notification is in the queue for sending.sending: Notification is currently being sent by a provider.sent: Notification has been sent from our system.delivered: Notification has been successfully delivered to the recipient's device/inbox.failed: Notification failed to deliver.opened: For email, the recipient opened the email.clicked: For email, the recipient clicked a link in the email.The PantheraHive Notifications API uses standard HTTP status codes to indicate the success or failure of an API request. In case of an error, the API will return a JSON object containing an error code, a human-readable message, and sometimes additional details.
| HTTP Status Code | Description |
| :--------------- | :-------------------------------------------- |
| 200 OK | The request was successful. |
| 202 Accepted | The request was accepted for processing. |
| 400 Bad Request| The request was malformed or invalid. |
| 401 Unauthorized| Authentication credentials were missing or invalid. |
| 403 Forbidden | You do not have permission to access this resource. |
| 404 Not Found | The requested resource could not be found. |
| 429 Too Many Requests| You have exceeded the rate limit. |
| 500 Internal Server Error| An unexpected error occurred on the server. |
Common Error Codes:
| Error Code | Description | Suggested Action |
| :-------------------- | :------------------------------------------------- | :---------------------------------------------------------------------------------- |
| INVALID_API_KEY | The provided API key is invalid or expired. | Check your API key. Generate a new one if necessary. |
| MISSING_PARAMETER | A required parameter is missing from the request. | Review the endpoint documentation and ensure all required parameters are included. |
| INVALID_PARAMETER | A parameter has an invalid value or format. | Check the data types and formats of your parameters. |
| TEMPLATE_NOT_FOUND | The specified template_id does not exist. | Verify the template_id in your PantheraHive dashboard. |
| RECIPIENT_INVALID | No valid recipient identifiers provided. | Ensure each recipient object has at least user_id, email, or phone. |
| RATE_LIMIT_EXCEEDED | You have sent too many requests in a given time. | Implement exponential backoff and retry mechanisms. Refer to Rate Limiting section. |
To ensure fair usage and system stability, the PantheraHive Notifications API enforces rate limits. If you exceed these limits, you will receive an HTTP 429 Too Many Requests status code.
Current Limits:
Headers for Rate Limit Information:
When you make an API request, the response headers will include information about your current rate limit status:
X-RateLimit-Limit: The maximum number of requests you can make in the current window.X-RateLimit-Remaining: The number of requests remaining in the current window.X-RateLimit-Reset: The time (in UTC epoch seconds) when the current rate limit window resets.Handling Rate Limits:
When a 429 error is received, we recommend implementing an exponential backoff strategy for retries. Do not immediately retry the request. Instead, wait for the duration specified in the Retry-After header (if present) or implement a progressively longer delay between retries.
To simplify your integration process, we offer official SDKs for popular programming languages. These SDKs handle authentication, request signing, and provide convenient methods for interacting with the API.
Stay tuned! We are continuously developing and releasing new SDKs to support a wider range of development environments.
We're here to help you succeed! If you encounter any issues, have questions, or would like to provide feedback, please reach out to us.
support@pantherahive.com.Start integrating the PantheraHive Notifications API today and elevate your application's communication capabilities.
[Sign Up for a Free PantheraHive Account](https://pantherahive.com/signup)
[Access Your Developer Dashboard](https://pantherahive.com/dashboard)
[Explore Notification Templates](https://pantherahive.com/templates)
This document provides a comprehensive guide to integrating with the Product Management API. It details available endpoints, authentication methods, request/response formats, and error handling. This API allows for programmatic management of products, categories, and related data within your system.
The Product Management API offers a robust set of RESTful endpoints designed to facilitate the creation, retrieval, updating, and deletion of product-related data. Developers can leverage this API to build custom integrations, automate product catalog updates, synchronize data across platforms, and extend the functionality of their existing applications.
Key Features:
The Product Management API uses API Key authentication. To authenticate your requests, you must include your unique API Key in the X-API-Key header of every request.
X-API-KeyYOUR_API_KEY (e.g., sk_live_xyz123abc456)Example Request Header:
GET /api/v1/products HTTP/1.1
Host: api.example.com
X-API-Key: sk_live_xyz123abc456
Content-Type: application/json
Obtaining Your API Key:
Your API Key can be generated and managed from your developer dashboard under "API Settings". Treat your API Key as a sensitive credential and keep it secure. Do not expose it in client-side code or public repositories.
All API requests should be made to the following base URL:
https://api.example.com/api/v1
In addition to the X-API-Key header, the following headers are generally recommended or required:
Content-Type: application/json (for requests with a body, e.g., POST, PUT)Accept: application/json (to explicitly request JSON responses)This section details all available endpoints, their methods, parameters, and example requests/responses.
##### 3.1.1. Get All Products
Retrieves a list of all products. Supports pagination and filtering.
/productsGET * page (Query, Integer, Optional): The page number to retrieve. Default is 1.
* limit (Query, Integer, Optional): The number of items per page. Max is 100. Default is 20.
* category_id (Query, String, Optional): Filter products by a specific category ID.
* status (Query, String, Optional): Filter products by status (e.g., active, draft, archived).
* 200 OK: Successfully retrieved the list of products.
* 401 Unauthorized: Invalid or missing API Key.
* 400 Bad Request: Invalid query parameters.
Example Request (cURL):
curl -X GET \
'https://api.example.com/api/v1/products?page=1&limit=10&status=active' \
-H 'Accept: application/json' \
-H 'X-API-Key: YOUR_API_KEY'
Example Response (200 OK):
{
"page": 1,
"limit": 10,
"total_items": 50,
"total_pages": 5,
"data": [
{
"id": "prod_abc123",
"name": "Wireless Bluetooth Headphones",
"description": "High-fidelity sound with active noise cancellation.",
"sku": "WH-BT-001",
"price": 99.99,
"currency": "USD",
"category_id": "cat_audio",
"status": "active",
"created_at": "2023-01-15T10:00:00Z",
"updated_at": "2023-01-15T10:00:00Z"
},
{
"id": "prod_xyz789",
"name": "Smartwatch Series 5",
"description": "Track your fitness and stay connected.",
"sku": "SW-S5-001",
"price": 249.00,
"currency": "USD",
"category_id": "cat_wearables",
"status": "active",
"created_at": "2023-02-20T14:30:00Z",
"updated_at": "2023-02-20T14:30:00Z"
}
]
}
##### 3.1.2. Get Product by ID
Retrieves a single product by its unique identifier.
/products/{product_id}GET * product_id (Path, String, Required): The unique ID of the product.
* 200 OK: Successfully retrieved the product.
* 401 Unauthorized: Invalid or missing API Key.
* 404 Not Found: Product with the given ID does not exist.
Example Request (cURL):
curl -X GET \
'https://api.example.com/api/v1/products/prod_abc123' \
-H 'Accept: application/json' \
-H 'X-API-Key: YOUR_API_KEY'
Example Response (200 OK):
{
"id": "prod_abc123",
"name": "Wireless Bluetooth Headphones",
"description": "High-fidelity sound with active noise cancellation.",
"sku": "WH-BT-001",
"price": 99.99,
"currency": "USD",
"category_id": "cat_audio",
"status": "active",
"created_at": "2023-01-15T10:00:00Z",
"updated_at": "2023-01-15T10:00:00Z"
}
##### 3.1.3. Create a New Product
Adds a new product to the catalog.
/productsPOST * name (String, Required): The name of the product.
* description (String, Optional): A detailed description of the product.
* sku (String, Required): Stock Keeping Unit, must be unique.
* price (Number, Required): The price of the product.
* currency (String, Required): The currency code (e.g., USD, EUR).
* category_id (String, Optional): The ID of the category this product belongs to.
* status (String, Optional): The initial status of the product. Default is draft.
* 201 Created: Successfully created the product.
* 400 Bad Request: Invalid request body or missing required fields.
* 401 Unauthorized: Invalid or missing API Key.
* 409 Conflict: A product with the given SKU already exists.
Example Request (cURL):
curl -X POST \
'https://api.example.com/api/v1/products' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-d '{
"name": "Gaming Mouse Pro",
"description": "Ergonomic gaming mouse with customizable RGB lighting.",
"sku": "GM-PRO-001",
"price": 79.99,
"currency": "USD",
"category_id": "cat_peripherals",
"status": "active"
}'
Example Response (201 Created):
{
"id": "prod_def456",
"name": "Gaming Mouse Pro",
"description": "Ergonomic gaming mouse with customizable RGB lighting.",
"sku": "GM-PRO-001",
"price": 79.99,
"currency": "USD",
"category_id": "cat_peripherals",
"status": "active",
"created_at": "2023-03-01T09:15:00Z",
"updated_at": "2023-03-01T09:15:00Z"
}
##### 3.1.4. Update a Product
Modifies an existing product. Only fields provided in the request body will be updated.
/products/{product_id}PUT (or PATCH for partial updates, assuming PUT for full replacement here) * product_id (Path, String, Required): The unique ID of the product to update.
* name (String, Optional): New name for the product.
* description (String, Optional): New description for the product.
* price (Number, Optional): New price for the product.
* currency (String, Optional): New currency for the product.
* category_id (String, Optional): New category ID.
* status (String, Optional): New status for the product.
* 200 OK: Successfully updated the product.
* 400 Bad Request: Invalid request body.
* 401 Unauthorized: Invalid or missing API Key.
* 404 Not Found: Product with the given ID does not exist.
Example Request (cURL):
curl -X PUT \
'https://api.example.com/api/v1/products/prod_abc123' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-d '{
"price": 89.99,
"status": "on_sale"
}'
Example Response (200 OK):
{
"id": "prod_abc123",
"name": "Wireless Bluetooth Headphones",
"description": "High-fidelity sound with active noise cancellation.",
"sku": "WH-BT-001",
"price": 89.99,
"currency": "USD",
"category_id": "cat_audio",
"status": "on_sale",
"created_at": "2023-01-15T10:00:00Z",
"updated_at": "2023-03-05T11:30:00Z"
}
##### 3.1.5. Delete a Product
Removes a product from the catalog.
/products/{product_id}DELETE * product_id (Path, String, Required): The unique ID of the product to delete.
* 204 No Content: Product successfully deleted.
* 401 Unauthorized: Invalid or missing API Key.
* 404 Not Found: Product with the given ID does not exist.
Example Request (cURL):
curl -X DELETE \
'https://api.example.com/api/v1/products/prod_abc123' \
-H 'X-API-Key: YOUR_API_KEY'
Example Response (204 No Content):
(No response body for 204 status)
##### 3.2.1. Get All Categories
Retrieves a list of all product categories.
/categoriesGET * page (Query, Integer, Optional): The page number to retrieve. Default is 1.
* limit (Query, Integer, Optional): The number of items per page. Max is 100. Default is 20.
* 200 OK: Successfully retrieved the list of categories.
* 401 Unauthorized: Invalid or missing API Key.
* 400 Bad Request: Invalid query parameters.
Example Request (cURL):
curl -X GET \
'https://api.example.com/api/v1/categories' \
-H 'Accept: application/json' \
-H 'X-API-Key: YOUR_API_KEY'
Example Response (200 OK):
{
"page": 1,
"limit": 20,
"total_items": 3,
"total_pages": 1,
"data": [
{
"id": "cat_audio",
"name": "Audio Devices",
"slug": "audio-devices",
"description": "Headphones, speakers, and other audio equipment.",
"created_at": "2022-10-01T08:00:00Z",
"updated_at": "2022-10-01T08:00:00Z"
},
{
"id": "