API Documentation

Validate

We can check if the user has entered a valid Token by querying /validate/ passing Authorization in as header using Bearer TOKEN.

curl --location --request GET 'https://api.photostack.io/validate/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
  {
      "message": "200 - Authenticated."
  }
]

List all Settings

curl --location --request GET 'https://api.photostack.io/settings/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "12345",
        "domain": "johnsmithphotography.com",
        "title": "John Smith Photography",
        "package": "Pro Unlimited",
        "usage": "220 GB / 1 TB",
        "limit_in_bytes": 1099511627776,
        "usage_in_bytes": 236223201280
    }
]

List all Clients

We can check if the user has entered a valid Token by querying /validate/ passing Authorization in as header using Bearer TOKEN.

curl --location --request GET 'https://api.photostack.io/clients/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "1",
        "client": "Joe's Windows LTD"
    },
    {
        "id": "2",
        "client": "Kate + John"
    }
]

List single Client

Specify an id number in the request URL to get a single client's details.

curl --location --request GET 'https://api.photostack.io/clients/1234/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "1234",
        "client": "Super Cool Hats"
    }
]

Create a new Client

Parameters required:

client string

The name of the new client in plain text.

curl --location --request POST 'https://api.photostack.io/clients/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5' \
--data-raw '{"client":"Oooober"}'

[
    {
        "id": "1234",
        "client": "Oooober"
    }
]

Update a Client

Update a client name by id. Parameters required:

client string

curl --location --request PATCH 'https://api.photostack.io/clients/1234/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5' \
--header 'Content-Type: application/json' \
--data-raw '{"client":"Super Cool Hats"}'

[
    {
        "id": "1234",
        "client": "Super Cool Hats"
    }
]

Delete a Client

Soft delete a client by id.

curl --location --request DELETE 'https://api.photostack.io/clients/1234/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
  {
      "message": "deleted"
  }
]

List all Collections

curl --location --request GET 'https://api.photostack.io/collections/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "1",
        "name": "Portraits",
        "url": "portraits",
        "type": "portfolio",
        "client": "0",
        "watermark": null,
        "watermark_originals": 0
    },
    {
        "id": "3",
        "name": "Kate + John",
        "url": "kate-and-john",
        "type": "client",
        "client": "2",
        "watermark": "2",
        "watermark_originals": 1
    }
]

List single Collection

Specify an id number in the request URL to get a single collection's details.

curl --location --request GET 'https://api.photostack.io/collections/3/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "3",
        "name": "Kate + John",
        "url": "kate-and-john",
        "type": "client",
        "client": "2",
        "watermark": "2",
        "watermark_originals": 1
    }
]

Create a new Collection

Parameters required:

name string

The name of the new collection in plain text.

client integer

For collection type of Portfolio set client to 0, for collection type of Client set the client to the relevant client ID.

Optional:

job integer

Link the collection to an existing job id. If set, job must belong to the same client.

watermark integer

Set a watermark id from /watermarks. Use 0 or omit to leave unset.

watermark_originals boolean|integer

Set to 1 (or true) to generate a watermarked full-resolution copy at /w/filename. Root original remains pristine.

curl --location --request POST 'https://api.photostack.io/collections/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5' \
--data-raw '{"name":"Oooober Head Shots", "client":"1234"}'

[
    {
        "id": "1234",
        "name": "Oooober Head Shots",
        "url": "oooober-head-shots",
        "client": "1234",
        "job": "987",
        "watermark": "2",
        "watermark_originals": 1
    }
]

Update a Collection

Update collection fields by id.

Accepted parameters:

name string
client integer
job integer
cover integer
watermark integer
watermark_originals boolean|integer

Set watermark to 0 to clear. If watermark is cleared, watermark_originals is forced to 0.

curl --location --request PATCH 'https://api.photostack.io/collections/3/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"Kate + John", "cover":"430", "watermark":"2", "watermark_originals":1}'

[
    {
        "id": "3",
        "name": "Kate + John",
        "url": "kate-and-john",
        "client": "2",
        "job": "0",
        "cover": "430",
        "watermark": "2",
        "watermark_originals": 1
    }
]

Delete a Collection

Soft delete a collection by id.

curl --location --request DELETE 'https://api.photostack.io/collections/3/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
  {
      "message": "deleted"
  }
]

List all Images in a Collection

Specify an id number in the request URL to get a collection's images. Optional filter: filename to match an exact filename.

curl --location --request GET 'https://api.photostack.io/collections/4/images/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "428",
        "collection": "4",
        "filename": "Oooober Head Shots - IMG_0480.jpg",
        "cdn": "https://cdn.photostack.io/images/collections/4/Oooober%20Head%20Shots%20-%20IMG_0480.jpg",
        "link": "https://example.com/portraits/#428"
    }
]

List single Image in a Collection

Specify an id number for both the collection and image in the request URL to get a specific image's data. Optional filter: filename to match an exact filename.

curl --location --request GET 'https://api.photostack.io/collections/4/images/430/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "430",
        "collection": "4",
        "filename": "Oooober Head Shots - IMG_0482.jpg",
        "cdn": "https://cdn.photostack.io/images/collections/4/Oooober%20Head%20Shots%20-%20IMG_0482.jpg",
        "link": "https://example.com/portraits/#430"
    }
]

Upload a new Image to a Collection

Specify an id number in the request URL to set the destination collection.

Parameters required:

upload file

The image to be uploaded should be sent as form-data with the key name upload.

Optional:

keywords string|array

Comma-separated keywords or an array to store on the image.

Images can be in the following formats:

.jpg
.jpeg
.png
.gif

Maximum file size allowed is 100MB.

curl --location --request POST 'https://api.photostack.io/collections/4/images/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5' \
--form 'upload=@"path/filename.jpg"'

[
    {
        "id": "430",
        "collection": "4",
        "filename": "filename.jpg",
        "cdn": "https://cdn.photostack.io/images/collections/4/filename.jpg",
        "link": "https://example.com/portraits/#430",
        "request": "abcd1234ef567890"
    }
]

Update Image keywords

Update image keywords by id. Parameters required:

keywords string|array

curl --location --request PATCH 'https://api.photostack.io/images/430/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5' \
--header 'Content-Type: application/json' \
--data-raw '{"keywords":"portraits, studio, headshot"}'

[
    {
        "id": 430,
        "keywords": ["portraits", "studio", "headshot"]
    }
]

Delete an Image

Soft delete an image by id.

curl --location --request DELETE 'https://api.photostack.io/images/430/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
  {
      "message": "deleted"
  }
]

Replace an Image

Replace the file for an existing image by id. Send upload as form-data. Optional keywords to update image keywords.

curl --location --request POST 'https://api.photostack.io/images/430/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5' \
--form 'upload=@"path/filename.jpg"'

[
    {
        "id": "430",
        "collection": "4",
        "filename": "filename.jpg",
        "cdn": "https://cdn.photostack.io/images/collections/4/filename.jpg",
        "link": "https://example.com/portraits/#430",
        "request": "abcd1234ef567890"
    }
]

List all Jobs

Returns all jobs for the authenticated account, ordered by start date.

curl --location --request GET 'https://api.photostack.io/jobs/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "55",
        "job": "Summer Campaign",
        "client": "2",
        "start": "2024-08-10",
        "finish": "2024-08-12",
        "stage": "editing"
    }
]

List single Job

Specify an id number in the request URL to get a single job.

curl --location --request GET 'https://api.photostack.io/jobs/55/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "55",
        "job": "Summer Campaign",
        "client": "2",
        "start": "2024-08-10",
        "finish": "2024-08-12",
        "stage": "editing"
    }
]

List Jobs by Client

Filter jobs by client id using the path /clients/:id/jobs/.

curl --location --request GET 'https://api.photostack.io/clients/2/jobs/' \
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "55",
        "job": "Summer Campaign",
        "client": "2",
        "start": "2024-08-10",
        "finish": "2024-08-12",
        "stage": "editing"
    }
]

List all Watermarks

Returns all active watermark presets for the authenticated account.

curl --location --request GET 'https://api.photostack.io/watermarks/' 
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "1",
        "name": "Studio Signature",
        "type": "text"
    },
    {
        "id": "2",
        "name": "White Logo",
        "type": "graphic"
    }
]

List single Watermark

Specify an id number in the request URL to get a single watermark.

curl --location --request GET 'https://api.photostack.io/watermarks/2/' 
--header 'Authorization: Bearer 1111-2222-3333-4444-5'

[
    {
        "id": "2",
        "name": "White Logo",
        "type": "graphic"
    }
]