[!WARNING] This SDK is incubating and subject to change.
The Foundry Platform SDK is a Python SDK built on top of the Foundry API. Review Foundry API documentation for more details.
[!NOTE] This Python package is automatically generated based on the Foundry API specification.
Palantir provides two different Python Software Development Kits (SDKs) for interacting with Foundry. Make sure to choose the correct SDK for your use case. As a general rule of thumb, any applications which leverage the Ontology should use the Ontology SDK for a superior development experience.
[!IMPORTANT] Make sure to understand the difference between the Foundry SDK and the Ontology SDK. Review this section before continuing with the installation of this library.
The Ontology SDK allows you to access the full power of the Ontology directly from your development environment. You can generate the Ontology SDK using the Developer Console, a portal for creating and managing applications using Palantir APIs. Review the Ontology SDK documentation for more information.
The Foundry Platform Software Development Kit (SDK) is generated from the Foundry API specification file. The intention of this SDK is to encompass endpoints related to interacting with the platform itself. Although there are Ontology services included by this SDK, this SDK surfaces endpoints for interacting with Ontological resources such as object types, link types, and action types. In contrast, the OSDK allows you to interact with objects, links and Actions (for example, querying your objects, applying an action).
You can install the Python package using pip
:
pip install foundry-platform-sdk
Every endpoint of the Foundry API is versioned using a version number that appears in the URL. For example, v1 endpoints look like this:
https://<hostname>/api/v1/...
This SDK exposes several clients, one for each major version of the API. For example, the latest major version of the
SDK is v2 and is exposed using the FoundryClient
located in the
foundry.v2
package. To use this SDK, you must choose the specific client (or clients)
you would like to use.
More information about how the API is versioned can be found here.
There are two options for authorizing the SDK.
[!WARNING] User tokens are associated with your personal Foundry user account and must not be used in production applications or committed to shared or public code repositories. We recommend you store test API tokens as environment variables during development. For authorizing production applications, you should register an OAuth2 application (see OAuth2 Client below for more details).
You can pass in the hostname and token as keyword arguments when
initializing the UserTokenAuth
:
import foundry
foundry_client = foundry.v2.FoundryClient(
auth=foundry.UserTokenAuth(
hostname="example.palantirfoundry.com",
token=os.environ["BEARER_TOKEN"],
),
hostname="example.palantirfoundry.com",
)
OAuth2 clients are the recommended way to connect to Foundry in production applications. Currently, this SDK natively supports the client credentials grant flow. The token obtained by this grant can be used to access resources on behalf of the created service user. To use this authentication method, you will first need to register a third-party application in Foundry by following the guide on third-party application registration.
To use the confidential client functionality, you first need to contstruct a ConfidentialClientAuth
object and initiate
the sign-in process using the sign_in_as_service_user
method. As these service user tokens have a short lifespan, we
automatically retry all operations one time if a 401
(Unauthorized) error is thrown after refreshing the token.
import foundry
auth = foundry.ConfidentialClientAuth(
client_id=os.environ["CLIENT_ID"],
client_secret=os.environ["CLIENT_SECRET"],
hostname="example.palantirfoundry.com",
scopes=["api:read-data"],
)
auth.sign_in_as_service_user()
[!IMPORTANT] Make sure to select the appropriate scopes when initializating the
ConfidentialClientAuth
. You can find the relevant scopes in the endpoint documentation.
After creating the ConfidentialClientAuth
object, pass it in to the FoundryClient
,
import foundry.v2
foundry_client = foundry.v2.FoundryClient(auth=auth, hostname="example.palantirfoundry.com")
Follow the installation procedure and determine which authentication method is
best suited for your instance before following this example. For simplicity, the UserTokenAuth
class will be used for demonstration
purposes.
from foundry.v1 import FoundryClient
import foundry
from pprint import pprint
foundry_client = FoundryClient(
auth=foundry.UserTokenAuth(...), hostname="example.palantirfoundry.com"
)
# DatasetRid | datasetRid
dataset_rid = "ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da"
# BranchId |
branch_id = "my-branch"
# Optional[TransactionRid] |
transaction_rid = None
try:
api_response = foundry_client.datasets.Dataset.Branch.create(
dataset_rid,
branch_id=branch_id,
transaction_rid=transaction_rid,
)
print("The create response:\n")
pprint(api_response)
except foundry.PalantirRPCException as e:
print("HTTP error when calling Branch.create: %s\n" % e)
Want to learn more about this Foundry SDK library? Review the following sections.
↳ Error handling: Learn more about HTTP & data validation error handling
↳ Pagination: Learn how to work with paginated endpoints in the SDK
↳ Static type analysis: Learn about the static type analysis capabilities of this library
The SDK employs Pydantic for runtime validation
of arguments. In the example below, we are passing in a number to transaction_rid
which should actually be a string type:
foundry_client.datasets.Dataset.Branch.create(
"ri.foundry.main.dataset.abc",
name="123",
transaction_rid=123,
)
If you did this, you would receive an error that looks something like:
pydantic_core._pydantic_core.ValidationError: 1 validation error for create
transaction_rid
Input should be a valid string [type=string_type, input_value=123, input_type=int]
For further information visit https://errors.pydantic.dev/2.5/v/string_type
To handle these errors, you can catch pydantic.ValidationError
. To learn more, see
the Pydantic error documentation.
[!TIP] Pydantic works with static type checkers such as pyright for an improved developer experience. See Static Type Analysis below for more information.
When an HTTP error status is returned, a PalantirRPCException
is thrown.
from foundry import PalantirRPCException
try:
api_response = foundry_client.datasets.Transaction.abort(dataset_rid, transaction_rid)
...
except PalantirRPCException as e:
print("Another HTTP exception occurred: " + str(e))
This exception will have the following properties. See the Foundry API docs for details about the Foundry error information.
Property | Type | Description |
---|---|---|
name | str | The Palantir error name. See the Foundry API docs. |
error_instance_id | str | The Palantir error instance ID. See the Foundry API docs. |
parameters | Dict[str, Any] | The Palantir error parameters. See the Foundry API docs. |
When calling any iterator endpoints, we return a Pager
class designed to simplify the process of working
with paginated API endpoints. This class provides a convenient way to fetch, iterate over, and manage pages
of data, while handling the underlying pagination logic.
To iterate over all items, you can simply create a Pager
instance and use it in a for loop, like this:
for branch in foundry_client.datasets.Dataset.Branch.list(dataset_rid):
print(branch)
This will automatically fetch and iterate through all the pages of data from the specified API endpoint. For more granular control, you can manually fetch each page using the associated page methods.
page = foundry_client.datasets.Dataset.Branch.page(dataset_rid)
while page.next_page_token:
for branch in page.data:
print(branch)
page = foundry_client.datasets.Dataset.Branch.page(dataset_rid, page_token=page.next_page_token)
This library uses Pydantic for creating and validating data models which you will see in the
method definitions (see Documentation for Models below for a full list of models). All request parameters with nested
models use a TypedDict whereas responses use Pydantic
models. For example, here is how Group.search
method is defined in the Admin
namespace:
@pydantic.validate_call
@handle_unexpected
def search(
self,
*,
where: GroupSearchFilterDict,
page_size: Optional[PageSize] = None,
page_token: Optional[PageToken] = None,
preview: Optional[PreviewMode] = None,
request_timeout: Optional[Annotated[pydantic.StrictInt, pydantic.Field(gt=0)]] = None,
) -> SearchGroupsResponse:
...
[!TIP] A
Pydantic
model can be converted into itsTypedDict
representation using theto_dict
method. For example, if you handle a variable of typeBranch
and you calledto_dict()
on that variable you would receive aBranchDict
variable.
If you are using a static type checker (for example, mypy, pyright), you
get static type analysis for the arguments you provide to the function and with the response. For example, if you pass an int
to name
but name
expects a string or if you try to access branchName
on the returned Branch
object (the
property is actually called name
), you will get the following errors:
branch = foundry_client.datasets.Dataset.Branch.create(
"ri.foundry.main.dataset.abc",
# ERROR: "Literal[123]" is incompatible with "BranchName"
name=123,
)
# ERROR: Cannot access member "branchName" for type "Branch"
print(branch.branchName)
This section will document any user-related errors with information on how you may be able to resolve them.
This error indicates you are trying to use an endpoint in public preview and have not set preview=True
when
calling the endpoint. Before doing so, note that this endpoint is
in preview state and breaking changes may occur at any time.
During the first phase of an endpoint's lifecycle, it may be in Public Preview
state. This indicates that the endpoint is in development and is not intended for
production use.
Namespace | Resource | Operation | HTTP request |
---|---|---|---|
Admin | Group | create | POST /v2/admin/groups |
Admin | Group | delete | DELETE /v2/admin/groups/{groupId} |
Admin | Group | get | GET /v2/admin/groups/{groupId} |
Admin | Group | get_batch | POST /v2/admin/groups/getBatch |
Admin | Group | list | GET /v2/admin/groups |
Admin | Group | page | GET /v2/admin/groups |
Admin | Group | search | POST /v2/admin/groups/search |
Admin | GroupMember | add | POST /v2/admin/groups/{groupId}/groupMembers/add |
Admin | GroupMember | list | GET /v2/admin/groups/{groupId}/groupMembers |
Admin | GroupMember | page | GET /v2/admin/groups/{groupId}/groupMembers |
Admin | GroupMember | remove | POST /v2/admin/groups/{groupId}/groupMembers/remove |
Admin | GroupMembership | list | GET /v2/admin/users/{userId}/groupMemberships |
Admin | GroupMembership | page | GET /v2/admin/users/{userId}/groupMemberships |
Admin | User | delete | DELETE /v2/admin/users/{userId} |
Admin | User | get | GET /v2/admin/users/{userId} |
Admin | User | get_batch | POST /v2/admin/users/getBatch |
Admin | User | get_current | GET /v2/admin/users/getCurrent |
Admin | User | list | GET /v2/admin/users |
Admin | User | page | GET /v2/admin/users |
Admin | User | profile_picture | GET /v2/admin/users/{userId}/profilePicture |
Admin | User | search | POST /v2/admin/users/search |
Datasets | Branch | create | POST /v2/datasets/{datasetRid}/branches |
Datasets | Branch | delete | DELETE /v2/datasets/{datasetRid}/branches/{branchName} |
Datasets | Branch | get | GET /v2/datasets/{datasetRid}/branches/{branchName} |
Datasets | Branch | list | GET /v2/datasets/{datasetRid}/branches |
Datasets | Branch | page | GET /v2/datasets/{datasetRid}/branches |
Datasets | Dataset | create | POST /v2/datasets |
Datasets | Dataset | get | GET /v2/datasets/{datasetRid} |
Datasets | Dataset | read_table | GET /v2/datasets/{datasetRid}/readTable |
Datasets | File | content | GET /v2/datasets/{datasetRid}/files/{filePath}/content |
Datasets | File | delete | DELETE /v2/datasets/{datasetRid}/files/{filePath} |
Datasets | File | get | GET /v2/datasets/{datasetRid}/files/{filePath} |
Datasets | File | list | GET /v2/datasets/{datasetRid}/files |
Datasets | File | page | GET /v2/datasets/{datasetRid}/files |
Datasets | File | upload | POST /v2/datasets/{datasetRid}/files/{filePath}/upload |
Datasets | Transaction | abort | POST /v2/datasets/{datasetRid}/transactions/{transactionRid}/abort |
Datasets | Transaction | commit | POST /v2/datasets/{datasetRid}/transactions/{transactionRid}/commit |
Datasets | Transaction | create | POST /v2/datasets/{datasetRid}/transactions |
Datasets | Transaction | get | GET /v2/datasets/{datasetRid}/transactions/{transactionRid} |
Filesystem | Folder | children | GET /v2/filesystem/folders/{folderRid}/children |
Filesystem | Folder | children_page | GET /v2/filesystem/folders/{folderRid}/children |
Filesystem | Folder | create | POST /v2/filesystem/folders |
Filesystem | Folder | get | GET /v2/filesystem/folders/{folderRid} |
OntologiesV2 | Action | apply | POST /v2/ontologies/{ontology}/actions/{action}/apply |
OntologiesV2 | Action | apply_batch | POST /v2/ontologies/{ontology}/actions/{action}/applyBatch |
OntologiesV2 | ActionTypeV2 | get | GET /v2/ontologies/{ontology}/actionTypes/{actionType} |
OntologiesV2 | ActionTypeV2 | list | GET /v2/ontologies/{ontology}/actionTypes |
OntologiesV2 | ActionTypeV2 | page | GET /v2/ontologies/{ontology}/actionTypes |
OntologiesV2 | Attachment | read | GET /v2/ontologies/attachments/{attachmentRid}/content |
OntologiesV2 | Attachment | upload | POST /v2/ontologies/attachments/upload |
OntologiesV2 | AttachmentPropertyV2 | get_attachment | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/attachments/{property} |
OntologiesV2 | AttachmentPropertyV2 | get_attachment_by_rid | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/attachments/{property}/{attachmentRid} |
OntologiesV2 | AttachmentPropertyV2 | read_attachment | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/attachments/{property}/content |
OntologiesV2 | AttachmentPropertyV2 | read_attachment_by_rid | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/attachments/{property}/{attachmentRid}/content |
OntologiesV2 | LinkedObjectV2 | get_linked_object | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/links/{linkType}/{linkedObjectPrimaryKey} |
OntologiesV2 | LinkedObjectV2 | list_linked_objects | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/links/{linkType} |
OntologiesV2 | LinkedObjectV2 | page_linked_objects | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/links/{linkType} |
OntologiesV2 | ObjectTypeV2 | get | GET /v2/ontologies/{ontology}/objectTypes/{objectType} |
OntologiesV2 | ObjectTypeV2 | get_outgoing_link_type | GET /v2/ontologies/{ontology}/objectTypes/{objectType}/outgoingLinkTypes/{linkType} |
OntologiesV2 | ObjectTypeV2 | list | GET /v2/ontologies/{ontology}/objectTypes |
OntologiesV2 | ObjectTypeV2 | list_outgoing_link_types | GET /v2/ontologies/{ontology}/objectTypes/{objectType}/outgoingLinkTypes |
OntologiesV2 | ObjectTypeV2 | page | GET /v2/ontologies/{ontology}/objectTypes |
OntologiesV2 | ObjectTypeV2 | page_outgoing_link_types | GET /v2/ontologies/{ontology}/objectTypes/{objectType}/outgoingLinkTypes |
OntologiesV2 | OntologyObjectSet | aggregate | POST /v2/ontologies/{ontology}/objectSets/aggregate |
OntologiesV2 | OntologyObjectSet | load | POST /v2/ontologies/{ontology}/objectSets/loadObjects |
OntologiesV2 | OntologyObjectV2 | aggregate | POST /v2/ontologies/{ontology}/objects/{objectType}/aggregate |
OntologiesV2 | OntologyObjectV2 | get | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey} |
OntologiesV2 | OntologyObjectV2 | list | GET /v2/ontologies/{ontology}/objects/{objectType} |
OntologiesV2 | OntologyObjectV2 | page | GET /v2/ontologies/{ontology}/objects/{objectType} |
OntologiesV2 | OntologyObjectV2 | search | POST /v2/ontologies/{ontology}/objects/{objectType}/search |
OntologiesV2 | OntologyV2 | get | GET /v2/ontologies/{ontology} |
OntologiesV2 | Query | execute | POST /v2/ontologies/{ontology}/queries/{queryApiName}/execute |
OntologiesV2 | QueryType | get | GET /v2/ontologies/{ontology}/queryTypes/{queryApiName} |
OntologiesV2 | QueryType | list | GET /v2/ontologies/{ontology}/queryTypes |
OntologiesV2 | QueryType | page | GET /v2/ontologies/{ontology}/queryTypes |
OntologiesV2 | TimeSeriesPropertyV2 | get_first_point | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/timeseries/{property}/firstPoint |
OntologiesV2 | TimeSeriesPropertyV2 | get_last_point | GET /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/timeseries/{property}/lastPoint |
OntologiesV2 | TimeSeriesPropertyV2 | stream_points | POST /v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/timeseries/{property}/streamPoints |
Orchestration | Build | create | POST /v2/orchestration/builds/create |
Orchestration | Build | get | GET /v2/orchestration/builds/{buildRid} |
Orchestration | Schedule | create | POST /v2/orchestration/schedules |
Orchestration | Schedule | delete | DELETE /v2/orchestration/schedules/{scheduleRid} |
Orchestration | Schedule | get | GET /v2/orchestration/schedules/{scheduleRid} |
Orchestration | Schedule | pause | POST /v2/orchestration/schedules/{scheduleRid}/pause |
Orchestration | Schedule | replace | PUT /v2/orchestration/schedules/{scheduleRid} |
Orchestration | Schedule | run | POST /v2/orchestration/schedules/{scheduleRid}/run |
Orchestration | Schedule | unpause | POST /v2/orchestration/schedules/{scheduleRid}/unpause |
ThirdPartyApplications | Version | delete | DELETE /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions/{versionVersion} |
ThirdPartyApplications | Version | get | GET /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions/{versionVersion} |
ThirdPartyApplications | Version | list | GET /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions |
ThirdPartyApplications | Version | page | GET /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions |
ThirdPartyApplications | Version | upload | POST /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/versions/upload |
ThirdPartyApplications | Website | deploy | POST /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/deploy |
ThirdPartyApplications | Website | get | GET /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website |
ThirdPartyApplications | Website | undeploy | POST /v2/thirdPartyApplications/{thirdPartyApplicationRid}/website/undeploy |
Namespace | Resource | Operation | HTTP request |
---|---|---|---|
Datasets | Branch | create | POST /v1/datasets/{datasetRid}/branches |
Datasets | Branch | delete | DELETE /v1/datasets/{datasetRid}/branches/{branchId} |
Datasets | Branch | get | GET /v1/datasets/{datasetRid}/branches/{branchId} |
Datasets | Branch | list | GET /v1/datasets/{datasetRid}/branches |
Datasets | Branch | page | GET /v1/datasets/{datasetRid}/branches |
Datasets | Dataset | create | POST /v1/datasets |
Datasets | Dataset | get | GET /v1/datasets/{datasetRid} |
Datasets | Dataset | read | GET /v1/datasets/{datasetRid}/readTable |
Datasets | File | delete | DELETE /v1/datasets/{datasetRid}/files/{filePath} |
Datasets | File | get | GET /v1/datasets/{datasetRid}/files/{filePath} |
Datasets | File | list | GET /v1/datasets/{datasetRid}/files |
Datasets | File | page | GET /v1/datasets/{datasetRid}/files |
Datasets | File | read | GET /v1/datasets/{datasetRid}/files/{filePath}/content |
Datasets | File | upload | POST /v1/datasets/{datasetRid}/files:upload |
Datasets | Transaction | abort | POST /v1/datasets/{datasetRid}/transactions/{transactionRid}/abort |
Datasets | Transaction | commit | POST /v1/datasets/{datasetRid}/transactions/{transactionRid}/commit |
Datasets | Transaction | create | POST /v1/datasets/{datasetRid}/transactions |
Datasets | Transaction | get | GET /v1/datasets/{datasetRid}/transactions/{transactionRid} |
Ontologies | Action | apply | POST /v1/ontologies/{ontologyRid}/actions/{actionType}/apply |
Ontologies | Action | apply_batch | POST /v1/ontologies/{ontologyRid}/actions/{actionType}/applyBatch |
Ontologies | Action | validate | POST /v1/ontologies/{ontologyRid}/actions/{actionType}/validate |
Ontologies | ActionType | get | GET /v1/ontologies/{ontologyRid}/actionTypes/{actionTypeApiName} |
Ontologies | ActionType | list | GET /v1/ontologies/{ontologyRid}/actionTypes |
Ontologies | ActionType | page | GET /v1/ontologies/{ontologyRid}/actionTypes |
Ontologies | ObjectType | get | GET /v1/ontologies/{ontologyRid}/objectTypes/{objectType} |
Ontologies | ObjectType | get_outgoing_link_type | GET /v1/ontologies/{ontologyRid}/objectTypes/{objectType}/outgoingLinkTypes/{linkType} |
Ontologies | ObjectType | list | GET /v1/ontologies/{ontologyRid}/objectTypes |
Ontologies | ObjectType | list_outgoing_link_types | GET /v1/ontologies/{ontologyRid}/objectTypes/{objectType}/outgoingLinkTypes |
Ontologies | ObjectType | page | GET /v1/ontologies/{ontologyRid}/objectTypes |
Ontologies | ObjectType | page_outgoing_link_types | GET /v1/ontologies/{ontologyRid}/objectTypes/{objectType}/outgoingLinkTypes |
Ontologies | Ontology | get | GET /v1/ontologies/{ontologyRid} |
Ontologies | Ontology | list | GET /v1/ontologies |
Ontologies | OntologyObject | aggregate | POST /v1/ontologies/{ontologyRid}/objects/{objectType}/aggregate |
Ontologies | OntologyObject | get | GET /v1/ontologies/{ontologyRid}/objects/{objectType}/{primaryKey} |
Ontologies | OntologyObject | get_linked_object | GET /v1/ontologies/{ontologyRid}/objects/{objectType}/{primaryKey}/links/{linkType}/{linkedObjectPrimaryKey} |
Ontologies | OntologyObject | list | GET /v1/ontologies/{ontologyRid}/objects/{objectType} |
Ontologies | OntologyObject | list_linked_objects | GET /v1/ontologies/{ontologyRid}/objects/{objectType}/{primaryKey}/links/{linkType} |
Ontologies | OntologyObject | page | GET /v1/ontologies/{ontologyRid}/objects/{objectType} |
Ontologies | OntologyObject | page_linked_objects | GET /v1/ontologies/{ontologyRid}/objects/{objectType}/{primaryKey}/links/{linkType} |
Ontologies | OntologyObject | search | POST /v1/ontologies/{ontologyRid}/objects/{objectType}/search |
Ontologies | Query | execute | POST /v1/ontologies/{ontologyRid}/queries/{queryApiName}/execute |
Ontologies | QueryType | get | GET /v1/ontologies/{ontologyRid}/queryTypes/{queryApiName} |
Ontologies | QueryType | list | GET /v1/ontologies/{ontologyRid}/queryTypes |
Ontologies | QueryType | page | GET /v1/ontologies/{ontologyRid}/queryTypes |
This repository does not accept code contributions.
If you have any questions, concerns, or ideas for improvements, create an issue with Palantir Support.
This project is made available under the Apache 2.0 License.