Pigment provides access to select Application and Block metadata for import and export APIs that require a Block, View, or Import Configuration ID. These APIs can also be used to build advanced integration UIs with user-friendly configuration dropdown menus.

Requirements and authentication

API key requirements

To access metadata API endpoints, you must use the Modeling Metadata API key type.

This API key inherits the Workspace, data visibility, and permissions of the user who created it. To prevent issues with data access or deactivated users, it’s recommended to use a service account for creating the API key.

Authentication process

Similar to import and export APIs, all metadata API endpoints have the same authentication based on API keys and Authorization HTTP header.

To authenticate each API call, you need to add a HTTP Authorization header to your request: 

Authorization: Bearer {API_KEY}

Replace the {API_KEY} with the key you generated in API Keys in your Workspace Settings.

Example call with a fake URL:

curl "https://pigment.app/api/v1/metadata" \
-H "Authorization: Bearer ${API_KEY}"

Response format

All metadata API endpoints return JSON responses.

Get Applications from Workspace

Lists all Applications in the Workspace associated with the API key.

Endpoint to retrieve Applications:

https://pigment.app/api/v1/applications

Example API call:

curl "https://pigment.app/api/v1/applications" \
-H "Authorization: Bearer ${API_KEY}"

Example response:

"
  {
    "id": "057f8f30-a9a0-4daf-becd-eadc08af93ae",
    "name": "My Application"
  },
  {
    "id": "2ad09a12-b5b0-4fc4-bcf1-f34d7771943c",
    "name": "Other Application"
  }
]

Get Blocks from an Application

Lists all Blocks in a specific Application in the Workspace associated with the API key.

Endpoint to retrieve Blocks:

https://pigment.app/api/v1/blocks?applicationId={APP_ID}

Example API call:

curl "https://pigment.app/api/v1/blocks?applicationId=057f8f30-a9a0-4daf-becd-eadc08af93ae" \
-H "Authorization: Bearer ${API_KEY}"

Example response:

a
  {
    "id": "312c1741-b762-481f-85c2-19ebe91a348a",
    "name": "Revenue per Country",
    "type": "Metric"
  },
  {
    "id": "adeb3492-3fed-48be-949e-683754f10777",
    "name": "Country",
    "type": "DimensionList"
  },
  {
    "id": "cbd6404e-0683-403f-bad8-62b520bacc49",
    "name": "Sales Transactions",
    "type": "TransactionList"
  },
  {
    "id": "d963374a-8363-47bb-9cbf-714f2e6f93db",
    "name": "Exec Reporting",
    "type": "Table"
  }
]

Get Views from a Block

Lists all Views in a specific Block in the Workspace associated with the API key.

Endpoint to retrieve Views:

https://pigment.app/api/v1/views?applicationId={APP_ID}&blockId={BLK_ID}

Example API call:

curl "https://pigment.app/api/v1/views?applicationId=057f8f30-a9a0-4daf-becd-eadc08af93ae&blockId=312c1741-b762-481f-85c2-19ebe91a348a" \
-H "Authorization: Bearer ${API_KEY}"

 Example response:

d
  {
    "id": "38bdcbd7-585e-4a81-87a5-520d9e2cc7f0",
    "name": "Default View",
    "type": "Public"
  },
  {
    "id": "f2f5edd7-e693-4071-9fce-fe7f16fb4379",
    "name": "View 2",
    "type": "Public"
  }
]

Get Import Configurations from a Block

Retrieves the details of import configurations associated with a specific Block in your Application.

Endpoint to retrieve Import Configurations:

https://pigment.app/api/v1/importConfigurations?applicationId={APP_ID}&blockId={BLK_ID}

Example API call:

curl "https://pigment.app/api/v1/importConfigurations?applicationId=057f8f30-a9a0-4daf-becd-eadc08af93ae&blockId=312c1741-b762-481f-85c2-19ebe91a348a" \
-H "Authorization: Bearer ${API_KEY}"

Example response:

>
  {
    "id": "3e904a36-bad3-413a-9db1-204d7911be57",
    "name": "CSV import config"
  }
]

Swagger / Open API specification

Visit the Pigment Swagger page to view all publicly available API endpoints.