Pinal Developers

API reference

Photos

Libraries, albums and uploads.

Base URL https://api.pinal.tech/v1

List photos

GET /photos

Library items, newest first, with thumbnails and metadata.

Query parameters

  • album string

    Album ID.

  • taken_after string (date-time)

    RFC 3339.

  • limit integer

    Items per page, 1–100.

  • cursor string

    Opaque cursor from a previous page's next_cursor.

Responses

curl "https://api.pinal.tech/v1/photos" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response · 200
{
  "photos": [
    {
      "id": "string",
      "kind": "photo",
      "filename": "string",
      "width": 0,
      "height": 0,
      "taken_at": "2026-11-19T15:20:04Z",
      "location": {
        "lat": 0,
        "lng": 0
      },
      "thumbnail_url": "https://example.com",
      "original_url": "https://example.com"
    }
  ],
  "next_cursor": "string"
}

Upload a photo

POST /photos

Uploads an image or video. With only photos.upload, the response omits other library items.

Request body multipart/form-data

  • file string (binary)
  • album string

Responses

curl -X POST "https://api.pinal.tech/v1/photos" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F file=@photo.jpg
Response · 201
{
  "id": "string",
  "kind": "photo",
  "filename": "string",
  "width": 0,
  "height": 0,
  "taken_at": "2026-11-19T15:20:04Z",
  "location": {
    "lat": 0,
    "lng": 0
  },
  "thumbnail_url": "https://example.com",
  "original_url": "https://example.com"
}

List albums

GET /photos/albums

Albums the app can see.

Responses

curl "https://api.pinal.tech/v1/photos/albums" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response · 200
{
  "albums": [
    {
      "id": "alb_77b0",
      "title": "Superstition Mountains",
      "count": 148
    }
  ]
}

Create an album

POST /photos/albums

Creates an album, optionally with items.

Request body application/json

  • title string required
  • photos array of string

Responses

curl -X POST "https://api.pinal.tech/v1/photos/albums" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "string",
    "photos": [
      "string"
    ]
  }'
Response · 201
{
  "id": "string",
  "title": "string",
  "count": 0,
  "cover": "string",
  "shared": true
}

Share an album

POST /photos/albums/{id}/share

Creates a shared album link.

Path parameters

  • id string required

    Album ID.

Request body application/json

  • expires_at string | null (date-time)

Responses

curl -X POST "https://api.pinal.tech/v1/photos/albums/{id}/share" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2026-11-19T15:20:04Z"
  }'
Response · 200
{
  "url": "string"
}