# Client data integration

Connect a script, dashboard, or scheduled job to your organization’s turtle profiles, sightings, and photos. The API provides read-only access.

## Get an API key

You need a version of AdaPenyu for Mac with organization API key controls and an AdaPenyu API environment that supports integration. Ask your administrator to confirm the HTTPS API address for your organization.

1. Sign in to your live organization in AdaPenyu for Mac as the organization owner.
2. Open **Settings** in the Mac app’s sidebar, then choose **Developer Options → Organization API Key**.
3. If you see **No API key configured**, choose **Generate API Key**. If you already have the active key saved, use it to connect your tool.
4. In **Save your new API key**, choose **Copy** or **Reveal**. Store the full key securely before selecting **I've saved it**.

> **Save the key before leaving Settings.** The full key is available only when issued. Rangers should ask the organization owner to manage the key. Key management requires a live account and is unavailable in demo mode.

## Connect and verify

Save the key as `ADAPENYU_API_KEY` in the secret settings for your integration server or job. Keep it out of source control, browser bundles, mobile apps, and logs.

With `ADAPENYU_API_KEY` available in your shell, set `BASE_URL` to the HTTPS origin for your organization’s API. Replace the example origin below. Send a single `X-API-Key` header with every integration request.

~~~bash
BASE_URL="https://api.example.com"

curl --fail \
  --header "X-API-Key: $ADAPENYU_API_KEY" \
  "$BASE_URL/api/integration/v1/individuals?limit=50&offset=0"
~~~

A `200 OK` confirms access. An empty `items` list is valid for an organization with no turtle profiles. The Mac app and the regular `/api/v1` and `/api/v2` endpoints use account sign-in and bearer tokens.

## Read turtle and sighting data

Send `GET` requests to the paths below using the `/api/integration/v1` prefix. Your key determines which organization’s records you can access.

### Pagination and filters

Start with `offset=0` and increase it by the page size to fetch the next page. The default `limit` is 50, the allowed range is 1–200, and `offset` must be zero or greater. Order is stable for a given dataset. Changes to records during pagination can shift results between pages.

- **Turtle profiles.** Use `q` to search, repeat `species` to select multiple species, or filter by `condition`. The default sort is `name`. Use `sort=last_seen_desc` to see the most recently sighted turtles first.
- **Organization-wide sightings.** Filter by observation time with `since` and `until`. By default, results include only identified turtles and can include sightings without coordinates. Set `identified_only=false` to include unidentified sightings, or `has_coordinates=true` to require coordinates.

~~~bash
curl --fail \
  --header "X-API-Key: $ADAPENYU_API_KEY" \
  "$BASE_URL/api/integration/v1/logs?identified_only=false&limit=50&offset=0"
~~~

## API response structure

List and detail requests return JSON. Resource IDs are UUID strings, timestamps are UTC, and missing values use `null` where the field permits it. Each [endpoint reference](#read-data) shows the response fields and a fictional example.

### List response

The three list endpoints return `items`, `total`, `limit`, and `offset`. The `/individuals` list contains turtle profiles. The organization-wide `/logs` list and a turtle’s history contain sightings. The `total` counts all results matching the request before pagination.

### Turtle profile

The detail endpoint returns the profile directly. The profile has identity photos by side and a summary of the turtle’s sightings. For full history, request `/individuals/{individual_id}/logs`. The summary’s latest sighting is a preview. Its latest measurements and latest recorded condition each reference the sighting that supplied those values.

### Sighting

The detail endpoint returns one sighting directly. An unidentified sighting can have `turtle_id: null`. When coordinates are available, `location.coordinates` contains `latitude` and `longitude`. Event fields depend on `event.type`. For example, a nesting event carries `egg_count`. Profiles and sightings use the v2 response shapes. Integration sightings omit saved matching snapshots.

When assessed, `condition` contains `status`, `notes`, and a `markings` array. Each marking has `id`, `region`, `kind`, `severity`, `notes`, `is_permanent`, `created_at`, and `updated_at`. A sighting photo’s `marking_id` can identify the marking it documents.

## Download photos

Set `PHOTO_PATH` to the relative `url` returned in a photo object. Request it from the same API origin with the key in the header. Keep the key out of the URL. The API sets `download_url` and `expires_at` to `null`.

~~~bash
curl --fail \
  --header "X-API-Key: $ADAPENYU_API_KEY" \
  --output turtle-photo \
  "$BASE_URL$PHOTO_PATH"
~~~

The response body contains the image bytes. The `Content-Type` header is `image/jpeg`, `image/png`, or `image/webp`, depending on the stored image.

## Manage access

Your organization has one active key at a time. An active key stays valid until you rotate it, revoke it, or delete the organization. Signing out or changing your account password leaves it active.

When Settings shows **Active key**, it displays the **Key prefix**, when the key was **Issued**, and the **Rotate Key** and **Revoke Key** controls.

- Choose **Rotate Key** to replace a lost key or change the key in use. Confirm the rotation, save the replacement, then update and verify every integration. The previous key stops authenticating requests as soon as rotation succeeds.
- Choose **Revoke Key** and confirm to stop access immediately. To reconnect, generate a new key and update each integration.
- If a change times out or its result is unclear, choose **Reload key status** before trying again. The change may have succeeded. If a new key was issued and you missed the one-time display, rotate to get another.

### Key management responses

Managing a key through the API requires an organization owner’s bearer access token.

- `GET /api/v1/organization/api-key` returns `200` with `configured`, `prefix`, and `issued_at`. With no active key, the values are `false`, `null`, and `null`.
- `POST /api/v1/organization/api-key/rotate` returns `200` with those fields plus the full `api_key` shown once.
- `DELETE /api/v1/organization/api-key` returns `204 No Content`, including when there is no active key.

## Troubleshooting

If the Mac app says organization API keys are unavailable, or the initial turtle list request returns `404`, check the API origin and integration availability with your administrator.

- **401 · Key rejected.** The response is `{"detail":"Invalid or missing API key"}` with `WWW-Authenticate: APIKey`. Use one `X-API-Key` header with the full current key. If the owner rotated the key, update the secret and retry.
- **404 · Resource unavailable.** Check the URL and confirm that the record or photo still exists in your organization.
- **405 · Method not allowed.** Send a `GET` request to read integration data.
- **422 · Invalid request.** Check the UUID, photo side, filter values, or pagination parameters in the response detail.
- **429 · Rate limit reached.** Wait for the number of seconds in `Retry-After` before trying again. The default response specifies 60 seconds.
- **503 · Photo storage unavailable.** Try the photo download again later.

The default quota is 60 authenticated requests per organization per fixed minute. All integrations share it, including photo downloads and resource lookups that return `404`. The quota continues across key rotation.

## API reference

[OpenAPI JSON](https://www.adapenyu.com/docs/client-data-integration/openapi.json)

### Turtle profiles

#### List turtle profiles

`GET /api/integration/v1/individuals`

Search and filter your organization’s turtle profiles. Each profile includes identity photos and a sighting summary.

**Authentication** · `X-API-Key` is required. The organization’s active integration key.

- `q` · query, optional, `string | null`. Search text for turtle profiles.

- `species` · query, optional, `array of TurtleSpecies | null`. A turtle species. Repeat the query parameter to select multiple species. Values hawksbill, green, loggerhead, leatherback, olive_ridley, unknown

- `condition` · query, optional, `HealthStatus | null`. Filter profiles by condition. Values unknown, healthy, scarred, injured

- `sort` · query, optional, `string`. Use name or last_seen_desc. Default "name"

- `limit` · query, optional, `integer`. Maximum number of records to return. Minimum 1. Maximum 200. Default 50

- `offset` · query, optional, `integer`. Number of records to skip. Minimum 0. Default 0

- **200** · Successful Response · `application/json` (`Page[TurtleProfile]`)

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **422** · Invalid fields, body, image, or current password · `application/json` (`ApiErrorOut`)

- **429** · Request quota exceeded; wait according to Retry-After · `application/json` (`ApiErrorOut`) · Headers Retry-After

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request GET \
  --url "$BASE_URL/api/integration/v1/individuals?limit=50&offset=0" \
  --header "X-API-Key: $ADAPENYU_API_KEY"
~~~

**200 · JSON**

~~~json
{
  "items": [
    {
      "id": "10000000-0000-4000-8000-000000000001",
      "profile_code": "000001",
      "name": "Example turtle",
      "species": "green",
      "sex": "unknown",
      "identity_photos": {
        "left": {
          "id": "30000000-0000-4000-8000-000000000001",
          "url": "/api/integration/v1/individuals/10000000-0000-4000-8000-000000000001/photos/left",
          "download_url": null,
          "expires_at": null,
          "captured_at": null,
          "uploaded_at": "2026-11-04T08:05:00Z"
        },
        "right": null
      },
      "summary": {
        "total_sightings": 1,
        "latest_sighting": {
          "id": "20000000-0000-4000-8000-000000000001",
          "observed_at": "2026-11-04T08:00:00Z",
          "event": {
            "type": "sighting"
          },
          "location": {
            "name": "Example site",
            "coordinates": null
          },
          "condition": null
        },
        "last_recorded_condition": null,
        "latest_measurements": {
          "log_id": "20000000-0000-4000-8000-000000000001",
          "observed_at": "2026-11-04T08:00:00Z",
          "values": {
            "carapace_length_cm": 62.5,
            "carapace_width_cm": 54.2,
            "weight_kg": null
          }
        }
      },
      "first_seen_at": "2026-11-04T08:00:00Z",
      "created_at": "2026-11-04T08:04:00Z",
      "updated_at": "2026-11-04T08:04:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
~~~

**401 · JSON**

~~~json
{
  "detail": "Invalid or missing API key"
}
~~~

**422 · JSON**

~~~json
{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": [
        "query",
        "limit"
      ],
      "msg": "Input should be greater than or equal to 1"
    }
  ]
}
~~~

**429 · JSON**

~~~json
{
  "detail": "Too many attempts; try again later"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~

#### Get a turtle profile

`GET /api/integration/v1/individuals/{individual_id}`

Get a turtle profile and its sighting summary by individual ID.

**Authentication** · `X-API-Key` is required. The organization’s active integration key.

- `individual_id` · path, required, `string · uuid`. The turtle profile ID.

- **200** · Successful Response · `application/json` (`TurtleProfile`)

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **404** · Resource not found or outside the authenticated organization · `application/json` (`ApiErrorOut`)

- **422** · Invalid fields, body, image, or current password · `application/json` (`ApiErrorOut`)

- **429** · Request quota exceeded; wait according to Retry-After · `application/json` (`ApiErrorOut`) · Headers Retry-After

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request GET \
  --url "$BASE_URL/api/integration/v1/individuals/10000000-0000-4000-8000-000000000001" \
  --header "X-API-Key: $ADAPENYU_API_KEY"
~~~

**200 · JSON**

~~~json
{
  "id": "10000000-0000-4000-8000-000000000001",
  "profile_code": "000001",
  "name": "Example turtle",
  "species": "green",
  "sex": "unknown",
  "identity_photos": {
    "left": {
      "id": "30000000-0000-4000-8000-000000000001",
      "url": "/api/integration/v1/individuals/10000000-0000-4000-8000-000000000001/photos/left",
      "download_url": null,
      "expires_at": null,
      "captured_at": null,
      "uploaded_at": "2026-11-04T08:05:00Z"
    },
    "right": null
  },
  "summary": {
    "total_sightings": 1,
    "latest_sighting": {
      "id": "20000000-0000-4000-8000-000000000001",
      "observed_at": "2026-11-04T08:00:00Z",
      "event": {
        "type": "sighting"
      },
      "location": {
        "name": "Example site",
        "coordinates": null
      },
      "condition": null
    },
    "last_recorded_condition": null,
    "latest_measurements": {
      "log_id": "20000000-0000-4000-8000-000000000001",
      "observed_at": "2026-11-04T08:00:00Z",
      "values": {
        "carapace_length_cm": 62.5,
        "carapace_width_cm": 54.2,
        "weight_kg": null
      }
    }
  },
  "first_seen_at": "2026-11-04T08:00:00Z",
  "created_at": "2026-11-04T08:04:00Z",
  "updated_at": "2026-11-04T08:04:00Z"
}
~~~

**401 · JSON**

~~~json
{
  "detail": "Invalid or missing API key"
}
~~~

**404 · JSON**

~~~json
{
  "detail": "Individual not found"
}
~~~

**422 · JSON**

~~~json
{
  "detail": [
    {
      "type": "uuid_parsing",
      "loc": [
        "path",
        "individual_id"
      ],
      "msg": "Input should be a valid UUID, invalid length: expected length 32 for simple format, found 3"
    }
  ]
}
~~~

**429 · JSON**

~~~json
{
  "detail": "Too many attempts; try again later"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~

#### List a turtle’s sightings

`GET /api/integration/v1/individuals/{individual_id}/logs`

Get a page of sightings from a single turtle’s history, newest first.

**Authentication** · `X-API-Key` is required. The organization’s active integration key.

- `individual_id` · path, required, `string · uuid`. The turtle profile ID.

- `limit` · query, optional, `integer`. Maximum number of records to return. Minimum 1. Maximum 200. Default 50

- `offset` · query, optional, `integer`. Number of records to skip. Minimum 0. Default 0

- **200** · Successful Response · `application/json` (`Page[IntegrationSighting]`)

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **404** · Resource not found or outside the authenticated organization · `application/json` (`ApiErrorOut`)

- **422** · Invalid fields, body, image, or current password · `application/json` (`ApiErrorOut`)

- **429** · Request quota exceeded; wait according to Retry-After · `application/json` (`ApiErrorOut`) · Headers Retry-After

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request GET \
  --url "$BASE_URL/api/integration/v1/individuals/10000000-0000-4000-8000-000000000001/logs?limit=50&offset=0" \
  --header "X-API-Key: $ADAPENYU_API_KEY"
~~~

**200 · JSON**

~~~json
{
  "items": [
    {
      "id": "20000000-0000-4000-8000-000000000001",
      "turtle_id": "10000000-0000-4000-8000-000000000001",
      "observed_at": "2026-11-04T08:00:00Z",
      "event": {
        "type": "sighting"
      },
      "location": {
        "name": "Example site",
        "coordinates": null
      },
      "condition": null,
      "behavior": null,
      "measurements": {
        "carapace_length_cm": 62.5,
        "carapace_width_cm": 54.2,
        "weight_kg": null
      },
      "identification": {
        "method": "manual",
        "confidence": null
      },
      "notes": null,
      "photos": [
        {
          "id": "30000000-0000-4000-8000-000000000002",
          "url": "/api/integration/v1/logs/20000000-0000-4000-8000-000000000001/photos/30000000-0000-4000-8000-000000000002",
          "download_url": null,
          "expires_at": null,
          "captured_at": "2026-11-04T08:00:00Z",
          "uploaded_at": "2026-11-04T08:06:00Z",
          "marking_id": null
        }
      ],
      "created_at": "2026-11-04T08:04:00Z",
      "updated_at": "2026-11-04T08:04:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
~~~

**401 · JSON**

~~~json
{
  "detail": "Invalid or missing API key"
}
~~~

**404 · JSON**

~~~json
{
  "detail": "Individual not found"
}
~~~

**422 · JSON**

~~~json
{
  "detail": [
    {
      "type": "uuid_parsing",
      "loc": [
        "path",
        "individual_id"
      ],
      "msg": "Input should be a valid UUID, invalid length: expected length 32 for simple format, found 3"
    }
  ]
}
~~~

**429 · JSON**

~~~json
{
  "detail": "Too many attempts; try again later"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~

#### Download an identity photo

`GET /api/integration/v1/individuals/{individual_id}/photos/{side}`

Download the left or right identity photo in its stored image format.

**Authentication** · `X-API-Key` is required. The organization’s active integration key.

- `individual_id` · path, required, `string · uuid`. The turtle profile ID.

- `side` · path, required, `TurtleSide`. The side of the turtle’s identity photo. Values left, right

- **200** · Binary download · `image/jpeg` (`string · binary`), `image/png` (`string · binary`), `image/webp` (`string · binary`)

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **404** · Resource not found or outside the authenticated organization · `application/json` (`ApiErrorOut`)

- **422** · Invalid fields, body, image, or current password · `application/json` (`ApiErrorOut`)

- **429** · Request quota exceeded; wait according to Retry-After · `application/json` (`ApiErrorOut`) · Headers Retry-After

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

- **503** · Storage, email delivery, or inference temporarily unavailable · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request GET \
  --url "$BASE_URL/api/integration/v1/individuals/10000000-0000-4000-8000-000000000001/photos/left" \
  --header "X-API-Key: $ADAPENYU_API_KEY" \
  --output "turtle-photo"
~~~

**200 · Binary**

Binary image data
image/jpeg
image/png
image/webp

**401 · JSON**

~~~json
{
  "detail": "Invalid or missing API key"
}
~~~

**404 · JSON**

~~~json
{
  "detail": "Photo not found"
}
~~~

**422 · JSON**

~~~json
{
  "detail": [
    {
      "type": "uuid_parsing",
      "loc": [
        "path",
        "individual_id"
      ],
      "msg": "Input should be a valid UUID, invalid length: expected length 32 for simple format, found 3"
    }
  ]
}
~~~

**429 · JSON**

~~~json
{
  "detail": "Too many attempts; try again later"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~

**503 · JSON**

~~~json
{
  "detail": "Photo storage temporarily unavailable"
}
~~~

### Sightings

#### List sightings

`GET /api/integration/v1/logs`

Get a page of your organization’s sightings. Set identified_only=false to include sightings without an identified turtle.

**Authentication** · `X-API-Key` is required. The organization’s active integration key.

- `since` · query, optional, `string · date-time | null`. Include sightings on or after this observation timestamp.

- `until` · query, optional, `string · date-time | null`. Include sightings on or before this observation timestamp.

- `identified_only` · query, optional, `boolean`. Set to false to include sightings without an identified turtle. Default true

- `has_coordinates` · query, optional, `boolean`. Set to true to require latitude and longitude. Default false

- `limit` · query, optional, `integer`. Maximum number of records to return. Minimum 1. Maximum 200. Default 50

- `offset` · query, optional, `integer`. Number of records to skip. Minimum 0. Default 0

- **200** · Successful Response · `application/json` (`Page[IntegrationSighting]`)

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **422** · Invalid fields, body, image, or current password · `application/json` (`ApiErrorOut`)

- **429** · Request quota exceeded; wait according to Retry-After · `application/json` (`ApiErrorOut`) · Headers Retry-After

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request GET \
  --url "$BASE_URL/api/integration/v1/logs?identified_only=false&limit=50&offset=0" \
  --header "X-API-Key: $ADAPENYU_API_KEY"
~~~

**200 · JSON**

~~~json
{
  "items": [
    {
      "id": "20000000-0000-4000-8000-000000000001",
      "turtle_id": "10000000-0000-4000-8000-000000000001",
      "observed_at": "2026-11-04T08:00:00Z",
      "event": {
        "type": "sighting"
      },
      "location": {
        "name": "Example site",
        "coordinates": null
      },
      "condition": null,
      "behavior": null,
      "measurements": {
        "carapace_length_cm": 62.5,
        "carapace_width_cm": 54.2,
        "weight_kg": null
      },
      "identification": {
        "method": "manual",
        "confidence": null
      },
      "notes": null,
      "photos": [
        {
          "id": "30000000-0000-4000-8000-000000000002",
          "url": "/api/integration/v1/logs/20000000-0000-4000-8000-000000000001/photos/30000000-0000-4000-8000-000000000002",
          "download_url": null,
          "expires_at": null,
          "captured_at": "2026-11-04T08:00:00Z",
          "uploaded_at": "2026-11-04T08:06:00Z",
          "marking_id": null
        }
      ],
      "created_at": "2026-11-04T08:04:00Z",
      "updated_at": "2026-11-04T08:04:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
~~~

**401 · JSON**

~~~json
{
  "detail": "Invalid or missing API key"
}
~~~

**422 · JSON**

~~~json
{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": [
        "query",
        "limit"
      ],
      "msg": "Input should be greater than or equal to 1"
    }
  ]
}
~~~

**429 · JSON**

~~~json
{
  "detail": "Too many attempts; try again later"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~

#### Get a sighting

`GET /api/integration/v1/logs/{log_id}`

Get a sighting’s event, location, condition, measurements, identification, and photo metadata.

**Authentication** · `X-API-Key` is required. The organization’s active integration key.

- `log_id` · path, required, `string · uuid`. The sighting ID.

- **200** · Successful Response · `application/json` (`IntegrationSighting`)

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **404** · Resource not found or outside the authenticated organization · `application/json` (`ApiErrorOut`)

- **422** · Invalid fields, body, image, or current password · `application/json` (`ApiErrorOut`)

- **429** · Request quota exceeded; wait according to Retry-After · `application/json` (`ApiErrorOut`) · Headers Retry-After

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request GET \
  --url "$BASE_URL/api/integration/v1/logs/20000000-0000-4000-8000-000000000001" \
  --header "X-API-Key: $ADAPENYU_API_KEY"
~~~

**200 · JSON**

~~~json
{
  "id": "20000000-0000-4000-8000-000000000001",
  "turtle_id": "10000000-0000-4000-8000-000000000001",
  "observed_at": "2026-11-04T08:00:00Z",
  "event": {
    "type": "sighting"
  },
  "location": {
    "name": "Example site",
    "coordinates": null
  },
  "condition": null,
  "behavior": null,
  "measurements": {
    "carapace_length_cm": 62.5,
    "carapace_width_cm": 54.2,
    "weight_kg": null
  },
  "identification": {
    "method": "manual",
    "confidence": null
  },
  "notes": null,
  "photos": [
    {
      "id": "30000000-0000-4000-8000-000000000002",
      "url": "/api/integration/v1/logs/20000000-0000-4000-8000-000000000001/photos/30000000-0000-4000-8000-000000000002",
      "download_url": null,
      "expires_at": null,
      "captured_at": "2026-11-04T08:00:00Z",
      "uploaded_at": "2026-11-04T08:06:00Z",
      "marking_id": null
    }
  ],
  "created_at": "2026-11-04T08:04:00Z",
  "updated_at": "2026-11-04T08:04:00Z"
}
~~~

**401 · JSON**

~~~json
{
  "detail": "Invalid or missing API key"
}
~~~

**404 · JSON**

~~~json
{
  "detail": "Log not found"
}
~~~

**422 · JSON**

~~~json
{
  "detail": [
    {
      "type": "uuid_parsing",
      "loc": [
        "path",
        "log_id"
      ],
      "msg": "Input should be a valid UUID, invalid length: expected length 32 for simple format, found 3"
    }
  ]
}
~~~

**429 · JSON**

~~~json
{
  "detail": "Too many attempts; try again later"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~

#### Download a sighting photo

`GET /api/integration/v1/logs/{log_id}/photos/{photo_id}`

Download a photo attached to a sighting in its stored image format.

**Authentication** · `X-API-Key` is required. The organization’s active integration key.

- `log_id` · path, required, `string · uuid`. The sighting ID.

- `photo_id` · path, required, `string · uuid`. The photo ID from the sighting’s photos array.

- **200** · Binary download · `image/jpeg` (`string · binary`), `image/png` (`string · binary`), `image/webp` (`string · binary`)

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **404** · Resource not found or outside the authenticated organization · `application/json` (`ApiErrorOut`)

- **422** · Invalid fields, body, image, or current password · `application/json` (`ApiErrorOut`)

- **429** · Request quota exceeded; wait according to Retry-After · `application/json` (`ApiErrorOut`) · Headers Retry-After

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

- **503** · Storage, email delivery, or inference temporarily unavailable · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request GET \
  --url "$BASE_URL/api/integration/v1/logs/20000000-0000-4000-8000-000000000001/photos/30000000-0000-4000-8000-000000000002" \
  --header "X-API-Key: $ADAPENYU_API_KEY" \
  --output "turtle-photo"
~~~

**200 · Binary**

Binary image data
image/jpeg
image/png
image/webp

**401 · JSON**

~~~json
{
  "detail": "Invalid or missing API key"
}
~~~

**404 · JSON**

~~~json
{
  "detail": "Photo not found"
}
~~~

**422 · JSON**

~~~json
{
  "detail": [
    {
      "type": "uuid_parsing",
      "loc": [
        "path",
        "log_id"
      ],
      "msg": "Input should be a valid UUID, invalid length: expected length 32 for simple format, found 3"
    }
  ]
}
~~~

**429 · JSON**

~~~json
{
  "detail": "Too many attempts; try again later"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~

**503 · JSON**

~~~json
{
  "detail": "Photo storage temporarily unavailable"
}
~~~

### Owner key management

#### Get API key status

`GET /api/v1/organization/api-key`

Check whether your organization has an active key and see its prefix and issue time.

**Authentication** · `Authorization` is required. An access token from normal sign-in as the organization owner.

- **200** · Successful Response · `application/json` (`OrganizationAPIKeyOut`)

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **403** · The authenticated account is not permitted to perform this operation · `application/json` (`ApiErrorOut`)

- **413** · Image or total request body exceeds its configured byte limit · `application/json` (`ApiErrorOut`)

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request GET \
  --url "$BASE_URL/api/v1/organization/api-key" \
  --header "Authorization: Bearer $OWNER_ACCESS_TOKEN"
~~~

**200 · JSON**

~~~json
{
  "configured": true,
  "prefix": "adapenyu_example",
  "issued_at": "2026-11-04T08:00:00Z"
}
~~~

**401 · JSON**

~~~json
{
  "detail": "Authentication required"
}
~~~

**403 · JSON**

~~~json
{
  "detail": "Owner access required"
}
~~~

**413 · JSON**

~~~json
{
  "detail": "Request body exceeds maximum size"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~

#### Generate or rotate the API key

`POST /api/v1/organization/api-key/rotate`

Issue a new key and return its full value once. If a key is already active, it stops working immediately.

**Authentication** · `Authorization` is required. An access token from normal sign-in as the organization owner.

- **200** · Successful Response · `application/json` (`OrganizationAPIKeyIssued`)

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **403** · The authenticated account is not permitted to perform this operation · `application/json` (`ApiErrorOut`)

- **413** · Image or total request body exceeds its configured byte limit · `application/json` (`ApiErrorOut`)

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request POST \
  --url "$BASE_URL/api/v1/organization/api-key/rotate" \
  --header "Authorization: Bearer $OWNER_ACCESS_TOKEN"
~~~

**200 · JSON**

~~~json
{
  "configured": true,
  "prefix": "adapenyu_example",
  "issued_at": "2026-11-04T08:00:00Z",
  "api_key": "<full key returned once>"
}
~~~

**401 · JSON**

~~~json
{
  "detail": "Authentication required"
}
~~~

**403 · JSON**

~~~json
{
  "detail": "Owner access required"
}
~~~

**413 · JSON**

~~~json
{
  "detail": "Request body exceeds maximum size"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~

#### Revoke the API key

`DELETE /api/v1/organization/api-key`

Revoke the current key. A repeated request after revocation also returns 204.

**Authentication** · `Authorization` is required. An access token from normal sign-in as the organization owner.

- **204** · No content

- **401** · Missing, invalid, expired, or revoked authentication credentials · `application/json` (`ApiErrorOut`) · Headers WWW-Authenticate

- **403** · The authenticated account is not permitted to perform this operation · `application/json` (`ApiErrorOut`)

- **413** · Image or total request body exceeds its configured byte limit · `application/json` (`ApiErrorOut`)

- **500** · Unexpected server error; internal details are withheld · `application/json` (`ApiErrorOut`)

~~~bash
curl --fail-with-body --request DELETE \
  --url "$BASE_URL/api/v1/organization/api-key" \
  --header "Authorization: Bearer $OWNER_ACCESS_TOKEN"
~~~

**204 · No content**

Empty response body

**401 · JSON**

~~~json
{
  "detail": "Authentication required"
}
~~~

**403 · JSON**

~~~json
{
  "detail": "Owner access required"
}
~~~

**413 · JSON**

~~~json
{
  "detail": "Request body exceeds maximum size"
}
~~~

**500 · JSON**

~~~json
{
  "detail": "Internal server error"
}
~~~
