Skip to content

add endpoint to create multiple status page subscribers #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MohamedEmadFahmy wants to merge 1 commit into
base: main
Choose a base branch
from
Open

add endpoint to create multiple status page subscribers #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 154 additions & 0 deletions instatus.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1830,6 +1830,46 @@
}
}
},
"/v1/{page_id}/subscribers/bulk": {
"post": {
"summary": "Add multiple subscribers",
"description": "Add multiple subscribers to a specific status page in a single request.\nMaximum 100 subscribers per request.\nPartial success is supported - successfully created subscribers are returned even if some fail.\n",
"tags": ["Subscribers"],
"parameters": [
{
"in": "path",
"name": "page_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the status page"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkAddSubscribersRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkAddSubscribersResponse"
}
}
}
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The endpoint only defines a 200 response but doesn't include error responses for common failure scenarios. Consider adding response definitions for 400 (bad request, e.g., invalid payload or exceeds 100 limit), 401 (unauthorized), and 404 (page not found) to properly document the API behavior.

Suggested change
}
}
},
"400": {
"description": "Bad request - invalid payload or exceeds 100 subscribers per request limit",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code identifying the type of validation error"
},
"message": {
"type": "string",
"description": "Human-readable description of the error"
}
},
"required": ["message"]
}
}
}
},
"401": {
"description": "Unauthorized - missing or invalid API token",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code indicating authentication failure"
},
"message": {
"type": "string",
"description": "Human-readable description of the authentication error"
}
},
"required": ["message"]
}
}
}
},
"404": {
"description": "Not found - the specified status page does not exist",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code indicating the resource was not found"
},
"message": {
"type": "string",
"description": "Human-readable description of the not found error"
}
},
"required": ["message"]
}
}
}

Copilot uses AI. Check for mistakes.
}
}
}
},
"/v1/{page_id}/subscribers/{subscriber_id}": {
"delete": {
"summary": "Remove a subscriber",
Expand Down Expand Up @@ -5861,6 +5901,120 @@
}
}
},
"BulkAddSubscribersRequest": {
"type": "object",
"required": ["subscribers"],
"properties": {
"subscribers": {
"type": "array",
"description": "Array of subscriber objects to create.",
"maxItems": 100,
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The subscribers array should have a minItems: 1 constraint. Allowing an empty array would make the request meaningless and could cause unexpected behavior. Add a minimum constraint to ensure at least one subscriber is provided.

Suggested change
"maxItems": 100,
"maxItems": 100,
"minItems": 1,

Copilot uses AI. Check for mistakes.
"items": {
"$ref": "#/components/schemas/AddSubscriberRequest"
}
},
"autoConfirm": {
"type": "boolean",
"description": "Whether subscribers are automatically confirmed or will receive an email to confirm their subscription. Applies to all subscribers in the batch. This is a paid feature."
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The autoConfirm property at the bulk request level creates ambiguity with the autoConfirm property that already exists in AddSubscriberRequest. If a subscriber in the array has autoConfirm: false but the bulk request has autoConfirm: true, it's unclear which takes precedence. Consider either removing the bulk-level autoConfirm and relying on the individual subscriber settings, or documenting that the bulk-level setting overrides individual settings.

Suggested change
"description": "Whether subscribers are automatically confirmed or will receive an email to confirm their subscription. Applies to all subscribers in the batch. This is a paid feature."
"description": "Whether subscribers are automatically confirmed or will receive an email to confirm their subscription. When this field is provided at the bulk request level, it applies to all subscribers in the batch and overrides any `autoConfirm` value specified on individual subscribers. This is a paid feature."

Copilot uses AI. Check for mistakes.
}
}
},
"BulkAddSubscribersResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether all subscribers were created successfully."
},
"created": {
"type": "integer",
"description": "Number of subscribers successfully created."
},
"failed": {
"type": "integer",
"description": "Number of subscribers that failed to be created."
},
"results": {
"type": "object",
"properties": {
"created": {
"type": "array",
"description": "List of successfully created subscribers.",
"items": {
"$ref": "#/components/schemas/BulkCreatedSubscriber"
}
},
"failed": {
"type": "array",
"description": "List of subscribers that failed to be created.",
"items": {
"$ref": "#/components/schemas/BulkFailedSubscriber"
}
}
}
}
}
},
"BulkCreatedSubscriber": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string",
"nullable": true
},
"phone": {
"type": "string",
"nullable": true
},
"name": {
"type": "string",
"nullable": true
},
"confirmed": {
"type": "boolean"
},
"all": {
"type": "boolean"
},
"site": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
}
}
}
Comment on lines +5958 to +5990
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The BulkCreatedSubscriber schema is missing several fields that are present in SubscriberDetail, such as components, webhook, webhookEmail, language, and other integration fields. This inconsistency could be confusing for API consumers who expect similar data between single and bulk creation responses. Consider either including these fields or documenting why they are intentionally omitted in the bulk response.

Copilot uses AI. Check for mistakes.
},
"BulkFailedSubscriber": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"description": "The index of the subscriber in the original request array."
},
"subscriber": {
"type": "object",
"description": "The subscriber data that was submitted."
Comment on lines +6000 to +6001
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The subscriber field is defined as a generic object without a schema reference. This makes it unclear what structure will be returned. Consider using $ref: "#/components/schemas/AddSubscriberRequest" or defining the specific properties to provide clear API documentation.

Suggested change
"type": "object",
"description": "The subscriber data that was submitted."
"description": "The subscriber data that was submitted.",
"allOf": [
{
"$ref": "#/components/schemas/AddSubscriberRequest"
}
]

Copilot uses AI. Check for mistakes.
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code identifying the type of failure."
},
"message": {
"type": "string",
"description": "Human-readable error message."
}
}
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error object properties should be marked as required to ensure consistent error reporting. Both code and message are essential for proper error handling and should not be optional.

Suggested change
}
},
"required": [
"code",
"message"
]

Copilot uses AI. Check for mistakes.
}
}
},
"SubscriberDetail": {
"type": "object",
"properties": {
Expand Down
112 changes: 112 additions & 0 deletions instatus.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1247,6 +1247,35 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/SubscriberDetail"
/v1/{page_id}/subscribers/bulk:
post:
summary: Add multiple subscribers
description: |
Add multiple subscribers to a specific status page in a single request.
Maximum 100 subscribers per request.
Partial success is supported - successfully created subscribers are returned even if some fail.
tags:
- Subscribers
parameters:
- in: path
name: page_id
required: true
schema:
type: string
description: The ID of the status page
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/BulkAddSubscribersRequest"
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/BulkAddSubscribersResponse"
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The endpoint only defines a 200 response but doesn't include error responses for common failure scenarios. Consider adding response definitions for 400 (bad request, e.g., invalid payload or exceeds 100 limit), 401 (unauthorized), and 404 (page not found) to properly document the API behavior.

Suggested change
$ref: "#/components/schemas/BulkAddSubscribersResponse"
$ref: "#/components/schemas/BulkAddSubscribersResponse"
"400":
description: Bad request - invalid payload or exceeded maximum of 100 subscribers per request
"401":
description: Unauthorized - missing or invalid authentication credentials
"404":
description: Not found - the specified status page does not exist

Copilot uses AI. Check for mistakes.
/v1/{page_id}/subscribers/{subscriber_id}:
delete:
summary: Remove a subscriber
Expand Down Expand Up @@ -4307,6 +4336,89 @@ components:
description: >-
The language of the subscriber in language code (e.g. `en` for
English, `fr` for French, `de` for German, etc.).
BulkAddSubscribersRequest:
type: object
required:
- subscribers
properties:
subscribers:
type: array
description: Array of subscriber objects to create.
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The subscribers array should have a minItems: 1 constraint. Allowing an empty array would make the request meaningless and could cause unexpected behavior. Add a minimum constraint to ensure at least one subscriber is provided.

Suggested change
description: Array of subscriber objects to create.
description: Array of subscriber objects to create.
minItems: 1

Copilot uses AI. Check for mistakes.
maxItems: 100
items:
$ref: "#/components/schemas/AddSubscriberRequest"
autoConfirm:
type: boolean
description: >-
Whether subscribers are automatically confirmed or will receive an
email to confirm their subscription. Applies to all subscribers in
the batch. This is a paid feature.
Comment on lines +4354 to +4355
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The autoConfirm property at the bulk request level creates ambiguity with the autoConfirm property that already exists in AddSubscriberRequest. If a subscriber in the array has autoConfirm: false but the bulk request has autoConfirm: true, it's unclear which takes precedence. Consider either removing the bulk-level autoConfirm and relying on the individual subscriber settings, or documenting that the bulk-level setting overrides individual settings.

Suggested change
email to confirm their subscription. Applies to all subscribers in
the batch. This is a paid feature.
email to confirm their subscription. When this field is provided
at the bulk request level, it applies to all subscribers in the
batch and overrides any `autoConfirm` value specified on individual
subscriber objects. If omitted, the `autoConfirm` setting of each
`AddSubscriberRequest` is used. This is a paid feature.

Copilot uses AI. Check for mistakes.
BulkAddSubscribersResponse:
type: object
properties:
success:
type: boolean
description: Whether all subscribers were created successfully.
created:
type: integer
description: Number of subscribers successfully created.
failed:
type: integer
description: Number of subscribers that failed to be created.
results:
type: object
properties:
created:
type: array
description: List of successfully created subscribers.
items:
$ref: "#/components/schemas/BulkCreatedSubscriber"
failed:
type: array
description: List of subscribers that failed to be created.
items:
$ref: "#/components/schemas/BulkFailedSubscriber"
BulkCreatedSubscriber:
type: object
properties:
id:
type: string
email:
type: string
nullable: true
phone:
type: string
nullable: true
name:
type: string
nullable: true
confirmed:
type: boolean
all:
type: boolean
site:
type: object
properties:
id:
type: string
BulkFailedSubscriber:
Comment on lines +4382 to +4404
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The BulkCreatedSubscriber schema is missing several fields that are present in SubscriberDetail, such as components, webhook, webhookEmail, language, and other integration fields. This inconsistency could be confusing for API consumers who expect similar data between single and bulk creation responses. Consider either including these fields or documenting why they are intentionally omitted in the bulk response.

Suggested change
type: object
properties:
id:
type: string
email:
type: string
nullable: true
phone:
type: string
nullable: true
name:
type: string
nullable: true
confirmed:
type: boolean
all:
type: boolean
site:
type: object
properties:
id:
type: string
BulkFailedSubscriber:
$ref: "#/components/schemas/SubscriberDetail"
BulkFailedSubscriber:
type: object
properties:
index:
type: integer
description: The index of the subscriber in the original request array.
subscriber:
type: object
description: The subscriber data that was submitted.
error:
type: object
properties:
code:
type: string
description: Error code identifying the type of failure.
message:
type: string
description: Human-readable error message.

Copilot uses AI. Check for mistakes.
type: object
properties:
index:
type: integer
description: The index of the subscriber in the original request array.
subscriber:
type: object
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The subscriber field is defined as a generic object without a schema reference. This makes it unclear what structure will be returned. Consider using $ref: "#/components/schemas/AddSubscriberRequest" or defining the specific properties to provide clear API documentation.

Suggested change
type: object
$ref: "#/components/schemas/AddSubscriberRequest"

Copilot uses AI. Check for mistakes.
description: The subscriber data that was submitted.
error:
type: object
properties:
code:
type: string
description: Error code identifying the type of failure.
message:
type: string
description: Human-readable error message.
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error object properties should be marked as required to ensure consistent error reporting. Both code and message are essential for proper error handling and should not be optional.

Suggested change
description: Human-readable error message.
description: Human-readable error message.
required:
- code
- message

Copilot uses AI. Check for mistakes.
SubscriberDetail:
type: object
properties:
Expand Down