GraphQL

Raster provides GraphQL APIs for accessing data. A read-only public API key is available for external access to allowed libraries. This key can be:

1. Initially created when needed
2. Regenerated if compromised
3. Deleted when no longer required

You can use this public API key to access permitted libraries outside of the Raster application through the Raster API.

Here's a curl example to get all the photos in a library:

curl --request POST \\
  --header 'Content-Type: application/json' \\
  --header 'Authorization: Bearer <API_KEY>' \\
  --url '<https://api.raster.app/>' \\
	--data '{"query": "query Photos { photos(organizationId: \\"monogram-labs\\", libraryId: \\"barcelona\\") { name url }}"}'

Make sure to replace the <API_KEY>, <ORG_ID> and the <LIBRARY_ID> with the appropriate values.

Authentication

The Raster API uses API keys to authenticate requests. You can view and manage your API keys in each organization's settings.

API access is granted through HTTP Basic Authentication. To authenticate, use your API key as the username in the basic auth process. No password is required.

You need to authenticate via bearer auth

"Authorization: Bearer pk_4eC39HqLH3U46nipzJ6ixhzdp7dc42Sf"

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

GraphQL Query Documentation

assets

Retrieves a list of assets from a specific library.

Parameters:

• organizationId: ID of the organization
• libraryId: ID of the library
• page: Page number for pagination (optional)
• pageSize: Number of items per page (optional, default 50, maximum 500)
• tags: Array of tags to filter assets (optional, maximum 5 tags)

Authentication:

Requires an API key with at least 'read' access to the specified library.

Returns:

An array of asset objects.

Return Properties:

• id: Unique identifier of the asset
• name: Name of the asset
• description: Optional text description of the asset
• thumbUrl: URL of the asset's thumbnail image
• url: URL to access the full size asset
• height: Height of the asset in pixels
• width: Width of the asset in pixels
• views: Array of view variants or renditions of the asset, each with:
• id: Unique identifier of the view
• parentId: Identifier of the original (parent) asset
• name: Name or label of the view
• url: URL to access this view
• height: Height of the view in pixels
• width: Width of the view in pixels

Notes:

• Performs an API key check and verifies library access before fetching assets.
• Throws an UNAUTHORIZED error if the API key is not authorized for the library.

Example Query:

query {
	assets(
		organizationId: "monogram-labs"
		libraryId: "barcelona"
		page: 1
		pageSize: 20
		tags: ["landscape", "nature"]
	) {
		id
		name
		type
		url
		tags
	}
}

libraries

Retrieves a list of libraries for a specific organization.

Parameters:

• organizationId: ID of the organization
• page: Page number for pagination (optional)
• pageSize: Number of items per page (optional, default 20, maximum 50)

Authentication:

Requires a valid API key.

Returns:

An array of library objects.

Return Properties:

• id: Unique identifier of the library
• name: Name of the library
• assetsCount: Total number of assets contained in the library
• trashCount: Number of items currently in the library’s trash
• tags: Array of tags associated with the library, each containing:
• id: Unique identifier of the tag (string)
• count: Number of times the tag has been used (number)
• type: Type of the tag (string)

Example Query:

query {
	libraries(organizationId: "monogram-labs", page: 1, pageSize: 10) {
		id
		name
		assetsCount
		trashCount
		tags {
			id
			count
			type
		}
	}
}

photos (DEPRECATED)

Note: 🚨 This query is deprecated. Use 'assets' instead.

Retrieves a list of photos (assets) from a specific library.

Parameters:

• organizationId: ID of the organization
• libraryId: ID of the library
• page: Page number for pagination (0-based indexing) (optional)

Authentication:

Requires an API key with at least 'read' access to the specified library.

Returns:

An array of photo (asset) objects.

Return Properties:

• id: Unique identifier of the photo
• name: Name of the photo
• url: URL to access the photo
• createdAt: Timestamp of photo creation
• updatedAt: Timestamp of last update
• metadata: Object containing additional metadata about the photo (e.g., dimensions, file size)

Notes:

• Performs an API key check and verifies library access before fetching photos.
• Throws an UNAUTHORIZED error if the API key is not authorized for the library.
• Always returns a fixed page size of 500 items.

Example Query:

query {
	photos(organizationId: "monogram-labs", libraryId: "barcelona", page: 1) {
		id
		name
		url
		createdAt
		updatedAt
		metadata
	}
}

tags

Retrieves tags associated with a specific library.

Parameters:

• organizationId: ID of the organization (required)
• libraryId: ID of the library (required)
• limit: Number of top tags to retrieve (optional)

Authentication:

Requires a valid API key with access to the specified library.

Returns:

An array of tag objects, sorted by count in descending order.

Return Properties:

• id: Unique identifier of the tag (string)
• count: Number of times the tag has been used (number)
• type: Type of the tag (string)

Notes:

• If limit is provided and greater than 0, it limits the number of returned tags.
• Tags are always sorted by count in descending order.
• Tags with IDs starting with '\*' will have this character removed in the response.
• If an error occurs during tag retrieval, it will be logged but not thrown.

Example Query:

query {
	tags(organizationId: "monogram-labs", libraryId: "barcelona", limit: 10) {
		id
		count
		type
	}
}

This query will return the top 10 tags for the specified library, sorted by usage count.

GraphQL Mutations Documentation

uploadAssets

Uploads multiple assets (up to 20 files) to a library.

Parameters:

• organizationId: ID of the organization (required)
• libraryId: ID of the library (required)
• files: Array of files to be uploaded (required, max 20 files)
• email: Email of the uploader (required)

Authentication: Requires an API key with 'write' access to the specified library.

Return Properties:

• responseText: Text response from the upload operation
• assets: Array of uploaded image objects, each containing:
• id: Unique identifier of the uploaded asset
• name: Name of the asset
• filename: Original filename
• contentType: MIME type of the file
• workspaceId: ID of the workspace
• organizationId: ID of the organization
• created: Timestamp of asset creation
• tags: Array of tags
• file: Object containing file details (size, type, name)
• status: Upload status
• progress: Upload progress
• uploadedBy: Object containing uploader details

Notes:

• Maximum of 20 files can be uploaded in a single request
• Performs an API key check and verifies library access before uploading
• Throws an UNAUTHORIZED error if the API key is not authorized for the library
• Validates each file type and size before uploading

Example Mutation

mutation {
	uploadAssets(
		organizationId: "monogram-labs"
		libraryId: "barcelona"
		files: [$file1, $file2]
		email: "[email protected]"
	) {
		responseText
		assets {
			id
			name
			filename
			contentType
			created
			tags
			status
			progress
		}
	}
}

deleteAssets

Deletes multiple assets in a single operation.

Parameters:

• organizationId: ID of the organization (required)
• libraryId: ID of the library (required)
• assets: Array of asset IDs to be deleted (required)

Authentication: Requires an API key with 'write' access to the specified library.

Return Properties:

• success: Boolean indicating if the deletion was successful
• message: Confirmation message
• ids: Array of deleted asset IDs

Notes:

• Performs an API key check and verifies library access before deleting the assets
• Throws an UNAUTHORIZED error if the API key is not authorized for the library
• Ensures all assets exist before attempting deletion
• All assets must belong to the specified library

Example Mutation:

mutation {
	deleteAssets(
		organizationId: "monogram-labs"
		libraryId: "barcelona"
		assets: ["asset-123", "asset-456"]
	) {
		success
		message
		ids
	}
}