# Ploi API Reference

## Purpose

Use this SOP when a human or agent needs to identify the official Ploi API documentation before working with Ploi servers, sites, databases, deployments, or related automation.

The current Ploi API documentation is published at:

```text
https://developers.ploi.io/
```

## Context

Ploi maintains its API documentation at `developers.ploi.io`. The documentation describes how to manage Ploi resources through HTTP API requests, including servers, sites, databases, deployments, and related server-management workflows.

The documentation also includes general API guidance for authorization, headers, URLs, scopes, pagination, query parameters, resource statuses, errors, rate limiting, and Ploi IP addresses.

## Outcome

After using this reference:

- A human can quickly open the latest Ploi API docs.
- An agent knows where to retrieve current Ploi API details instead of relying on stale memory.
- Ploi API work starts from the official documentation source.
- Secrets such as Ploi API tokens stay out of source control, chat logs, screenshots, and generated docs.

## Steps

1. Open the official Ploi API documentation:

   ```text
   https://developers.ploi.io/
   ```

2. Start with the **Getting started** and **Authorization** sections before making API calls.
3. Confirm the required API token scopes for the task.
4. Read the endpoint-specific resource documentation before choosing request payloads or response handling.
5. Check pagination, rate limiting, and error documentation for any workflow that lists or mutates multiple resources.
6. If the task involves deployments, read the deployment-specific documentation before triggering production deploy actions.
7. If the task involves servers or sites, read the server or site resource documentation before creating, updating, or deleting anything.

## Validation

Before implementing Ploi API work, verify:

- The documentation URL loads successfully.
- The relevant endpoint exists in the current Ploi docs.
- The required authentication method and token scopes are understood.
- The task does not require storing API tokens in the repository.
- Any production mutation has explicit user approval.

## Operational notes for agents

Always treat `https://developers.ploi.io/` as the source of truth for current Ploi API behavior.

Do not invent endpoint paths, request bodies, response shapes, scopes, or rate limits from memory. Retrieve the relevant documentation page first.

When asked to automate Ploi, search this SOP with terms such as Ploi API, Ploi documentation, Ploi servers, Ploi sites, Ploi deployments, authorization, scopes, and rate limiting.

## Troubleshooting

- If `https://developers.ploi.io/` is unavailable, pause and ask the user whether to continue with cached or previously known documentation.
- If an endpoint is missing from the docs, do not assume it exists.
- If an API token is missing, ask the user to create one from their Ploi profile and provide it through a secure secret mechanism.
- If an API request fails with authorization or scope errors, revisit the Authorization and Scopes documentation.
- If list requests are incomplete, check the Pagination documentation.
- If requests are throttled, check the Rate Limiting documentation.