{% extends "docs/base.html" %}

{% block docs_content %}
  <div class="d-flex flex-wrap align-items-center justify-content-between gap-2 mb-4">
    <div>
      <h1 class="h3 mb-1">API documentation</h1>
      <p class="text-muted mb-0">HTTP API usage, authentication, and paging.</p>
    </div>
    <div class="d-flex gap-2">
      <a class="btn btn-sm btn-outline-secondary active" href="/docs/api">API docs</a>
      <a class="btn btn-sm btn-outline-secondary" href="/api/v1/openapi.json">OpenAPI JSON</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/file-uploads">File uploads docs</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli">CLI docs</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/skills">Skills docs</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/work">Work docs</a>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="overview"><a class="link-body-emphasis text-decoration-none" href="#overview">Overview</a></h2>
      <p class="mb-2">
        The pearing HTTP API is a JSON API served under the <code>/api/v1</code> prefix. It uses API
        tokens for authentication and supports pagination for list endpoints.
      </p>
      <p class="mb-0">
        Path identifiers use human-friendly values (<code>username</code>, <code>team_slug</code>,
        <code>repo_slug</code>, and pull <code>number</code>). UUIDs are still returned in JSON
        response bodies, but are not used in API URL paths.
      </p>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="environment"><a class="link-body-emphasis text-decoration-none" href="#environment">Environment</a></h2>
      <p class="mb-2">
        The CLI and examples below use environment variables for the API base URL and token.
      </p>
      <ul class="mb-2">
        <li><code>PEARING_API_URL</code> should point to the API root (for example, <code>https://example.com/api</code>).</li>
        <li><code>PEARING_API_TOKEN</code> should be set to your API token.</li>
      </ul>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>export PEARING_API_URL="https://example.com/api"
export PEARING_API_TOKEN="your-token-here"</code></pre>
      </div>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="authentication"><a class="link-body-emphasis text-decoration-none" href="#authentication">Authentication</a></h2>
      <p class="mb-2">
        Create an API token from your profile at <a href="/profile/tokens">/profile/tokens</a>. Tokens are only shown once.
      </p>
      <p class="mb-2">Send the token using either:</p>
      <ul class="mb-2">
        <li><code>Authorization: Bearer &lt;token&gt;</code></li>
        <li><code>Authorization: Basic &lt;base64(:token)&gt;</code> (token as the password, empty username)</li>
      </ul>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>curl \
  --header "Authorization: Bearer $PEARING_API_TOKEN" \
  "$PEARING_API_URL/v1/users/self"</code></pre>
      </div>
      <div class="bg-light border rounded p-3 mt-2">
        <pre class="mb-0"><code>curl \
  --user ":$PEARING_API_TOKEN" \
  "$PEARING_API_URL/v1/users/self"</code></pre>
      </div>
    </div>
  </div>

  <div class="card shadow-sm">
    <div class="card-body">
      <h2 class="h5 mb-2" id="pagination"><a class="link-body-emphasis text-decoration-none" href="#pagination">Pagination</a></h2>
      <p class="mb-2">
        List endpoints accept <code>page</code> (1-based) and <code>per_page</code> query parameters.
        Responses return a page object with <code>results</code>, plus <code>next</code> and
        <code>previous</code> links when available.
      </p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>GET /api/v1/users?page=2&amp;per_page=50</code></pre>
      </div>
      <div class="bg-light border rounded p-3 mt-2">
        <pre class="mb-0"><code>{
  "next": "https://example.com/api/v1/users?page=3&amp;per_page=50",
  "previous": "https://example.com/api/v1/users?page=1&amp;per_page=50",
  "results": [
    { "...": "..." }
  ]
}</code></pre>
      </div>
    </div>
  </div>

  <div class="card shadow-sm mt-4 mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="errors"><a class="link-body-emphasis text-decoration-none" href="#errors">Error Format</a></h2>
      <p class="mb-2">Errors return JSON in this shape:</p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>{
  "error": "staff_only",
  "detail": "Only available to staff."
}</code></pre>
      </div>
      <p class="text-muted mb-0 mt-2">
        <code>error</code> is a machine-readable error code. <code>detail</code> is a human-readable description.
      </p>
    </div>
  </div>

  <div class="card shadow-sm mt-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="common-errors"><a class="link-body-emphasis text-decoration-none" href="#common-errors">Common Auth Errors</a></h2>
      <p class="mb-2">Most authenticated endpoints can return:</p>
      <ul class="mb-0">
        <li><code>401 Unauthorized</code> with <code>error: "api_token"</code> and <code>detail: "Invalid API token."</code>.</li>
        <li><code>403 Forbidden</code> with codes like <code>user_inactive</code>, <code>staff_only</code>, <code>api_token_inactive</code>, and <code>api_token_expired</code>.</li>
      </ul>
    </div>
  </div>
{% endblock %}