Pushify API Documentation

When you get an email#

Every active project with a live deployment and a URL is called about once a minute — no configuration needed. These are the conditions that send mail:

The app stops answering

Three failed checks in a row, so a single restart is not an outage. A second email arrives when it answers again, saying how long it was out. Without a configured health check any answer counts as up — a 404 on / is a missing route, not a down app.

Memory above 90% of the limit for 5 minutes

Past this the kernel is choosing what to kill next, and the usual result is a restart loop. This is the warning that arrives before the app stops answering. Ignored where no memory limit is set, since the percentage would then be of the whole server.

CPU above 90% for 15 minutes

Much longer than memory, because a build or a batch job legitimately saturates a CPU. The app is not down — requests are queuing behind it.

A server disk crosses its warning level

Checked hourly, not just at deploy time. A full disk takes every container on the box down together, databases included. One reminder a day while it stays full.

An HTTPS certificate is about to expire

Fourteen days before, then once more three days before. Renewal is automatic until something stops it — DNS moved, port 80 blocked.

Who gets them#

Everyone in the organization with deployment alerts turned on, in their own notification settings. A project's notification channels (Slack, Discord, webhooks) also receive the up/down events.

How long logs are kept#

Container output is collected from every container a project runs — the app, its replicas, its workers and its staging copy — and is searchable by term, time range and container. How long it stays depends on the plan:

Scaling on load#

Project settings → Scale automatically gives a minimum and a maximum, and Pushify moves the container count between them as CPU changes. Pro plan and above. Left off, the count stays exactly where you set it.

• One container at a time: a reading of 100% CPU adds one, not five — a container takes time to start and the reading cannot yet know whether one more is enough.
• Added above 70% average CPU, and not again for three minutes. Removed below 30%, and not again for ten — a lull at lunchtime should not undo a busy morning.
• At least three readings before anything happens, so a single spike changes nothing.
• Changing the minimum or maximum applies immediately, without waiting for a threshold or a cooldown: the range is an instruction, the thresholds are a guess.
• A new container is started from what the last deploy actually used, so it cannot differ from the ones already running. A project deployed before autoscaling existed starts scaling after its next deploy.
• Scaling down takes the container out of nginx and reloads before stopping it, so requests already in flight finish.
• Every change is written down with the reading that caused it, and listed in project settings.
• Not sure the thresholds suit your app? Turn on "Only report what it would do": the decision still runs and is recorded, but nothing changes. Watch for a few days, then decide.

Backups and what an interval costs#

A managed database is backed up automatically. The interval you pick is your worst-case data loss: at 24 hours, losing the disk costs a day of writes. The plan sets the shortest interval available — a day on Free, 12 hours on Hobby, 6 on Pro, hourly on Business and Enterprise.

• A database that has never been backed up is backed up at once rather than waiting out its first interval.
• Where the operator has configured off-site storage, each dump is also copied off the server it was made on — and a restore falls back to that copy, so a database can be restored onto a server that has never seen the file.
• The backup list shows whether an off-site copy exists for each backup.
• Deleting a database deletes its backups, off-site copies included.

Private registries#

Settings → Private registries stores one login per registry for the whole organization. It is used for two things: a Dockerfile whose FROM is a private base image, and projects that deploy a ready image. The token is write-only — it is sent once and never shown again, only replaced.

Deploying a ready image#

Project settings → Docker image: fill in a reference and the project deploys that image instead of building the repository. Every deploy pulls the reference again, so moving a tag and redeploying ships the new image.

ghcr.io/acme/api:1.4

• The image keeps everything it already declares — its CMD, ENV and exposed port are used as they are.
• It gets the same treatment as a built app: blue-green switch, replicas, staging, volumes, domains and HTTPS.
• The repository settings below the field stop applying, and the dashboard says so.
• A private image needs a registry credential for its host — see above.
• This needs a server; the no-server fallback cannot pull images.

Deploying a compose stack#

Project settings → Docker Compose file: give the path of a compose file in your repository and the project is deployed as a stack from your checkout, so build: contexts and the config files beside it work as they do locally. It is off by default and never picked up on its own — most repositories carry a compose file meant for local development, and deploying that would be a surprise.

services:
  web:
    build: ./web
    ports:
      - "8080:3000"
    environment:
      API: http://api:4000
  api:
    build: ./api

• Services reach each other by name on the stack network, exactly as they do locally.
• When more than one service publishes a port, name the one to serve in the settings — otherwise the deploy is refused rather than guessing.
• The project's environment variables are available to the stack, and a committed .env is read first.
• Pushify's Workers and Scheduled tasks drive a single container and do not apply — declare those as services in the compose file. The deploy log says so rather than ignoring them.
• A redeploy takes the stack down and brings it up, so unlike a built app it is not zero-downtime.

Before you start#

You need to be the organization's owner. Open Settings → Single sign-on: it shows the redirect URI your provider must send people back to. Copy it now — every provider asks for it first.

https://api.pushify.dev/api/v1/sso/callback

Okta#

1. In the Okta admin console, go to Applications → Create App Integration.
2. Choose OIDC – OpenID Connect, then Web Application.
3. Under Sign-in redirect URIs, paste the redirect URI from Pushify.
4. Under Assignments, pick who may use it — only these people will be able to sign in.
5. Save, then copy the Client ID and Client secret from the General tab.

https://YOUR-TENANT.okta.com

Microsoft Entra ID (Azure AD)#

1. In the Azure portal, open Microsoft Entra ID → App registrations → New registration.
2. For Redirect URI choose Web and paste the one from Pushify.
3. After registering, note the Application (client) ID and the Directory (tenant) ID.
4. Go to Certificates & secrets → New client secret and copy the secret Value (not the ID — the Value is only shown once).
5. Under Token configuration, add the optional claim email, and tick the box to turn on the Microsoft Graph email permission if it offers.

https://login.microsoftonline.com/YOUR-TENANT-ID/v2.0

Google Workspace#

1. In Google Cloud Console, pick the project for your organization and open APIs & Services → Credentials.
2. Create Credentials → OAuth client ID → Web application.
3. Under Authorised redirect URIs, paste the one from Pushify.
4. Copy the Client ID and Client secret.
5. On the OAuth consent screen, set User type to Internal so only your Workspace accounts can use it.

https://accounts.google.com

Finish in Pushify#

1. Settings → Single sign-on: enter the issuer, client ID and client secret.
2. Add the email domains your organization owns — only addresses in these sign in through the provider. Public providers such as gmail.com are refused, because anyone can have one.
3. Pick the role a new member gets the first time your provider sends them.
4. Save. Pushify contacts the provider before storing anything, so a wrong issuer is refused here rather than by the first person who tries to sign in.
5. Sign out and enter an address in one of those domains on the login page — the password field is replaced with a single button.

Requiring SSO#

With "Require single sign-on" on, passwords, GitHub and Google all stop working for those domains. That is the point of it: disabling someone in your identity provider is then enough to lock them out of Pushify. Two-factor authentication still applies on top — SSO says who someone is, it does not waive a second factor you asked for.

When it does not work#

The provider says the redirect URI does not match

Copy it again from Settings → Single sign-on. It is derived from your API address, so it changes if that does.

"is not verified with the identity provider"

The provider sent an address it has not verified. In Entra, add the email optional claim; in Okta, check the user has a verified primary email.

"is not in a domain this connection signs in"

The address is real but its domain is not on your list. Add it, or have the person use their work address. Sub-domains do not count: @eu.acme.com is not @acme.com.

The sign-in could not be verified

The token failed signature or claim checks. Usually the client secret is wrong or expired — Entra secrets expire, often after six months.

Everyone is locked out

On the server, delete the row from sso_connections for your organization; password login works again immediately.