Create a new app
const url = 'https://api.aetherpush.com/v1/apps';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"my-react-native-app","manuallyProvisionDeployments":false}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.aetherpush.com/v1/apps \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-react-native-app", "manuallyProvisionDeployments": false }'Creates a new app under the current account. By default, two
deployments named Production and Staging are auto-provisioned
in the same transaction as the app: either the create returns 201
with both deployments, or it fails and leaves no app row. Pass
manuallyProvisionDeployments: true to skip this and create
deployments manually; the app then comes back with an empty
deployments list.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
When true, the app is created without the default Production
and Staging deployments. Defaults to false.
Example
{ "name": "my-react-native-app", "manuallyProvisionDeployments": false}Responses
Section titled “Responses”App created.
object
object
Map keyed by collaborator email.
object
object
App role. Owner controls the app; Admin manages collaborators and deployments on top of Developer; Developer performs release operations; Viewer is read-only.
List of deployment names registered under this app.
Named permissions the requesting account holds on this app.
Example
{ "app": { "name": "my-react-native-app", "deployments": [ "Production", "Staging" ] }}Headers
Section titled “Headers”Validation error.
Standard error envelope. code is the stable machine identifier for
client branching and i18n. The wording of error is a human-readable
fallback and is not part of the contract. Specialized responses keep
narrower code enums where clients already branch on them.
object
Human-readable error message.
Stable machine code. Prefer this over matching on error. The
values this API can answer with are listed in the ApiErrorCode
schema of the raw document at
https://api.aetherpush.com/openapi.yaml. The field stays an
open string here so that a release adding a value does not
invalidate this response.
Unique identifier for the request, also exposed as the X-Request-Id response header.
object
object
Stable machine code for this field error.
Example
{ "error": "The requested resource was not found.", "code": "not_found", "requestId": "req_abc123"}Unauthenticated.
Standard error envelope. code is the stable machine identifier for
client branching and i18n. The wording of error is a human-readable
fallback and is not part of the contract. Specialized responses keep
narrower code enums where clients already branch on them.
object
Human-readable error message.
Stable machine code. Prefer this over matching on error. The
values this API can answer with are listed in the ApiErrorCode
schema of the raw document at
https://api.aetherpush.com/openapi.yaml. The field stays an
open string here so that a release adding a value does not
invalidate this response.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Example
{ "error": "The requested resource was not found.", "code": "not_found", "requestId": "req_abc123"}The API key’s scopes do not grant apps, which answers
required_scopes. A refusal raised before the route is reached,
such as a request that did not arrive through the trusted edge,
answers a plain error instead.
Standard error envelope. code is the stable machine identifier for
client branching and i18n. The wording of error is a human-readable
fallback and is not part of the contract. Specialized responses keep
narrower code enums where clients already branch on them.
object
Human-readable error message.
Stable machine code. Prefer this over matching on error. The
values this API can answer with are listed in the ApiErrorCode
schema of the raw document at
https://api.aetherpush.com/openapi.yaml. The field stays an
open string here so that a release adding a value does not
invalidate this response.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Returned when an API key’s scopes do not grant the scope a management
route requires. required_scopes lists what the route asked for, not
what the key holds. Access keys and login sessions carry wildcard
scope and pass the check without reaching this response, so only
apiKeyAuth callers receive it. A key whose only scope is keys gets
this on every management route, because that scope grants nothing,
which is also why keys never appears in required_scopes.
object
The scopes the route requires. Only these three appear: no
management route requires keys.
Examples
The API key's scopes do not grant apps
{ "error": "Insufficient permissions", "code": "insufficient_scopes", "required_scopes": [ "apps" ], "requestId": "req_abc123"}Refused before the route, here by the trusted edge
{ "error": "Forbidden", "code": "forbidden", "requestId": "req_abc123"}An app with that name already exists.
Standard error envelope. code is the stable machine identifier for
client branching and i18n. The wording of error is a human-readable
fallback and is not part of the contract. Specialized responses keep
narrower code enums where clients already branch on them.
object
Human-readable error message.
Stable machine code. Prefer this over matching on error. The
values this API can answer with are listed in the ApiErrorCode
schema of the raw document at
https://api.aetherpush.com/openapi.yaml. The field stays an
open string here so that a release adding a value does not
invalidate this response.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Example
{ "error": "The requested resource was not found.", "code": "not_found", "requestId": "req_abc123"}Three causes share this status. The tenant limiter answers
RateLimitErrorResponse (error, retryAfterSeconds) with Retry-After.
The plan’s app quota and a default-seed deployment-per-app
quota both answer the Error envelope and no Retry-After.
Default seed requires room for Production and Staging; when
max_deployments_per_app is below 2 the create rolls back and
leaves no app.
Returned with HTTP 429 when an endpoint-specific rate limit is hit,
including the per-tenant management API budget. Not the process-wide
address limiter (see GlobalAddressRateLimitErrorResponse).
retryAfterSeconds
indicates how long the client should wait before retrying, and matches
the Retry-After header when that header is set. code names the
limit that fired so clients can translate without matching on error.
object
Standard error envelope. code is the stable machine identifier for
client branching and i18n. The wording of error is a human-readable
fallback and is not part of the contract. Specialized responses keep
narrower code enums where clients already branch on them.
object
Human-readable error message.
Stable machine code. Prefer this over matching on error. The
values this API can answer with are listed in the ApiErrorCode
schema of the raw document at
https://api.aetherpush.com/openapi.yaml. The field stays an
open string here so that a release adding a value does not
invalidate this response.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Examples
Tenant management budget spent
{ "error": "Rate limit exceeded", "code": "tenant_rate_limit_exceeded", "retryAfterSeconds": 60}The plan's app quota is spent
{ "error": "App limit reached. Your plan allows a maximum of 3 apps.", "code": "quota_exceeded", "requestId": "req_abc123"}Default Production and Staging cannot fit under the per-app deployment quota
{ "error": "Deployment limit reached. Maximum 1 deployments per app.", "code": "quota_exceeded", "requestId": "req_abc123"}Headers
Section titled “Headers”Present only for the tenant limiter.