Skip to content

Projects HTTP API

Audience: Data Owners, Data Users, and Data Governors

Content Summary: This page details how to use the Projects API to query projects and the data sources associated with projects in Immuta.

Search All Projects

Method Path Successful Status Code
GET /project 200

Query Parameters

  • nameOnly (boolean, default false): When true, searchText will only filter by project name, allowing you to retrieve specific projects.
    • Example: "nameOnly=true&searchText=my-project-name" returns only one hit.
  • offset (integer, default 0): Used in combination with size to fetch pages.
    • Example: "size=10&offset=10" would return the second page.
    • Example: size=10&offset=10" would return the third page.
  • searchText (string): Searches text. By default this will filter projects by name, description, documentation, category, and organization.
  • size (integer, default 10): The number of results to return per page.
  • sortField (string): Used to sort results by field, which must be freshness, name, category, organization, status, or updatedAt.
  • sortOrder (string, default asc): Sorts results by order, which must be asc or desc.

Example Request List All Projects:

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project

Example Request Search for Top 5 Projects:

These projects will be sorted by the most recently updated.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
     https://demo.immuta.com/project?size=5&sortField=updatedAt&sortOrder=desc

Response

Responses include the following object attributes:

  • hits: array of project metadata
  • count: total number of results available; the number of results in the hits array may be less, depending on the size query parameter.

Example:

{
    "hits":
    [
        {
            "id": 1,
            "name": "proj1",
            "status": "open",
            "description": "sample",
            "organization": "Immuta",
            "category": "testing",
            "deleted": false,
            "private": true,
            "updatedAt": "2018-03-09T17:09:53.021Z",
            "createdAt": "2018-03-09T17:09:06.559Z",
            "filterId": 3,
            "subscriptionStatus": "not_subscribed",
            "purposeCount": 2,
            "hasCustomPurposes": true,
            "hasDeletedPurposes": false
        },
        {
            "id": 2,
            "name": "proj2",
            "status": "open",
            "description": null,
            "organization": null,
            "category": null,
            "deleted": false,
            "private": false,
            "updatedAt": "2018-03-09T17:08:39.901Z",
            "createdAt": "2018-03-09T17:08:39.889Z",
            "filterId": 2,
            "subscriptionStatus": "not_subscribed",
            "purposeCount": 0,
            "hasCustomPurposes": false,
            "hasDeletedPurposes": false
        }
    ],
    "count": 3
}

Search Data Sources Associated with a Project

Method Path Successful Status Code
GET /project{projectId}/dataSources 200

Query Parameters

  • size (integer, default 15): Pages results by default; size is the number of results to return per page.
  • offset (integer, default 0): Used in combination with size to fetch pages.
    • Example: "size=10&offset=10" would return the second page.
    • Example: "size=10&offset=20" would return the third page.
  • searchText (string): Searches text; this will filter project data sources by name.
  • sortField (string): Sorts results by field, which must be dataSourceName, addedOn, addedBy, or freshness.
  • sortOrder (string, default asc): Sorts results by order, which must be asc or desc.

Example Request Project Data Sources:

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project{projectId}/dataSources

Response

Responses include the following object attributes:

  • count: total number of data source in the project.
  • dataSources: array of data source metadata.

Example:

{
    "count": 1,
    "dataSources": [
        {
            "addedBy": "Immuta User",
            "dataSourceName": "hive_books",
            "addedOn": "2018-03-09T21:42:32.113Z",
            "dataSourceId": 14,
            "addedByProfile": 19,
            "comment": null,
            "roots": [],
            "deleted": false,
            "private": true,
            "subscriptionStatus": "not_subscribed"
        }
    ]
}