{% 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">Attachments</h1>
      <p class="text-muted mb-0">Attach an existing repo upload to a thread, reply, pull, or pull review.</p>
    </div>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/file-uploads">File uploads</a>
      <a class="btn btn-sm btn-outline-secondary active" href="/docs/api/attachments">Attachments</a>
      <a class="btn btn-sm btn-outline-secondary" href="/api/v1/openapi.json">OpenAPI JSON</a>
    </div>
  </div>

  <div class="alert alert-info mb-4" role="note">
    Attachment requests only link uploads that already exist in the same repo. Create the upload first
    with the <a href="/docs/api/create-file-upload">file upload API</a>, then send its
    <code>upload_uuid</code>. Attachment endpoints do not accept file bytes.
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2">Attach</h2>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>POST /api/v1/teams/{team_slug}/repos/{repo_slug}/threads/{number}/attachments
POST /api/v1/teams/{team_slug}/repos/{repo_slug}/threads/{number}/replies/{reply_number}/attachments
POST /api/v1/teams/{team_slug}/repos/{repo_slug}/pulls/{number}/attachments
POST /api/v1/teams/{team_slug}/repos/{repo_slug}/pulls/{number}/reviews/{review_uuid}/attachments

POST /api/v1/users/{username}/repos/{repo_slug}/threads/{number}/attachments
POST /api/v1/users/{username}/repos/{repo_slug}/threads/{number}/replies/{reply_number}/attachments
POST /api/v1/users/{username}/repos/{repo_slug}/pulls/{number}/attachments
POST /api/v1/users/{username}/repos/{repo_slug}/pulls/{number}/reviews/{review_uuid}/attachments</code></pre>
      </div>
      <p class="mt-3 mb-2">Send a JSON body containing the existing upload UUID:</p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>{
  "upload_uuid": "93dc0846-f01f-46a5-83b1-782bef8d7229"
}</code></pre>
      </div>
      <p class="text-muted small mb-0 mt-3">
        The upload must be active and belong to the target repo. A closed pull can receive an
        attachment; a merged pull, removed thread or reply, and removed pull review cannot.
      </p>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2">Detach</h2>
      <p class="mb-2">Append <code>/{upload_uuid}</code> to any attach endpoint and send <code>DELETE</code>.</p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>DELETE /api/v1/teams/{team_slug}/repos/{repo_slug}/threads/{number}/attachments/{upload_uuid}
DELETE /api/v1/users/{username}/repos/{repo_slug}/pulls/{number}/reviews/{review_uuid}/attachments/{upload_uuid}</code></pre>
      </div>
      <p class="text-muted small mb-0 mt-3">
        Detaching remains available after the upload or target is removed and after a pull is
        merged. The user who created the attachment can always detach it.
      </p>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2">Permissions</h2>
      <ul class="mb-0">
        <li>Thread attachments require the thread creator.</li>
        <li>Reply attachments require the reply creator.</li>
        <li>Pull attachments require the pull creator or a repo maintainer.</li>
        <li>Pull review attachments require the review author.</li>
      </ul>
    </div>
  </div>

  <div class="card shadow-sm">
    <div class="card-body">
      <h2 class="h5 mb-2">Responses and errors</h2>
      <ul class="mb-2">
        <li><code>201 Created</code> returns upload metadata, attachment attribution, and active upload links.</li>
        <li><code>204 No Content</code> confirms a detach.</li>
        <li><code>403 Forbidden</code> indicates missing write access or an archived repo.</li>
        <li><code>404 Not Found</code> indicates a missing target, upload, or attachment.</li>
        <li><code>409 Conflict</code> indicates a duplicate, removed upload, or read-only target.</li>
      </ul>
      <p class="text-muted small mb-0">
        Successful attach and detach operations emit <code>attachment-created</code> and
        <code>attachment-deleted</code> events with repo and target scopes.
      </p>
    </div>
  </div>
{% endblock %}