Projects
The access-control class of a project, governing who can see it.
PRIVATE: visible only to the project's ACL members (the default).SHARED: visible more broadly across the organization.CONFIDENTIAL: restricted, most tightly controlled access.
Attributes:
| Name | Type | Description |
|---|---|---|
SHARED |
|
|
CONFIDENTIAL |
|
|
PRIVATE |
|
The lifecycle state of a project.
The set of allowed states is customizable per tenant via the entity-status
API; these are the platform defaults. Unknown tenant-specific values are
tolerated as plain strings on Project.state.
Attributes:
| Name | Type | Description |
|---|---|---|
NOT_STARTED |
|
|
ACTIVE |
|
|
CLOSED_SUCCESS |
|
|
CLOSED_ARCHIVED |
|
|
JUST_STARTED |
|
|
IN_PROGRESS |
|
Bases: BaseAlbertModel
Default task settings applied when tasks are created within a project.
Show JSON schema:
{
"description": "Default task settings applied when tasks are created within a project.",
"properties": {
"datatemplateId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of the data template tasks default to.",
"title": "Datatemplateid"
},
"workflowId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of the workflow tasks default to.",
"title": "Workflowid"
},
"defaultTaskName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Default name applied to new tasks.",
"title": "Defaulttaskname"
},
"target": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Default target for the configured tasks.",
"title": "Target"
},
"hidden": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether this configuration is hidden in the UI.",
"title": "Hidden"
}
},
"title": "TaskConfig",
"type": "object"
}
Fields:
-
datatemplateId(str | None) -
workflowId(str | None) -
defaultTaskName(str | None) -
target(str | None) -
hidden(bool | None)
Bases: BaseSessionResource
A project in Albert: the top-level container for a piece of R&D work.
A project groups the formulations designed for the work, its Worksheet (1:1
with the project), the Tasks run against it, and the inventory it references.
Create and manage projects through the
ProjectCollection (client.projects).
Only description is required to build one; it doubles as the project's
display name. The id and state are assigned by Albert and are read
only from the client's perspective.
Example
Show JSON schema:
{
"$defs": {
"ACL": {
"description": "A single access rule for a user.",
"properties": {
"id": {
"description": "The id of the user for which this ACL applies",
"title": "Id",
"type": "string"
},
"fgc": {
"anyOf": [
{
"$ref": "#/$defs/AccessControlLevel"
},
{
"type": "null"
}
],
"default": null,
"description": "The Fine-Grain Control Level"
}
},
"required": [
"id"
],
"title": "ACL",
"type": "object"
},
"AccessControlLevel": {
"description": "Access control levels you can grant users.",
"enum": [
"ProjectOwner",
"ProjectEditor",
"ProjectViewer",
"ProjectAllTask",
"ProjectStrictViewer",
"ProjectPropertyTask",
"InventoryOwner",
"InventoryViewer",
"CustomTemplateOwner",
"CustomTemplateViewer",
"CASFullAccess"
],
"title": "AccessControlLevel",
"type": "string"
},
"AuditFields": {
"description": "The audit fields for a resource",
"properties": {
"by": {
"default": null,
"title": "By",
"type": "string"
},
"byName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Byname"
},
"at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "At"
}
},
"title": "AuditFields",
"type": "object"
},
"EntityLink": {
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category"
}
},
"required": [
"id"
],
"title": "EntityLink",
"type": "object"
},
"EntityLinkWithName": {
"description": "EntityLink that includes the name field in serialization.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category"
}
},
"required": [
"id"
],
"title": "EntityLinkWithName",
"type": "object"
},
"GridDefault": {
"description": "The default grid view shown for a project.\n\n- ``PD``: the Property Data grid.\n- ``WKS``: the Worksheet grid.",
"enum": [
"PD",
"WKS"
],
"title": "GridDefault",
"type": "string"
},
"Location": {
"description": "A physical lab or site location in Albert.\n\nLocations are referenced by Tasks and Inventory Items to record where an\nactivity is performed or where a material lives, and each Location can hold\none or more Storage Locations\n([`StorageLocation`][albert.resources.storage_locations.StorageLocation]). Managed\nthrough [`LocationCollection`][albert.collections.locations.LocationCollection].\n\n!!! example\n ```python\n from albert.resources.locations import Location\n location = Location(\n name=\"Boston Lab\",\n latitude=42.3601,\n longitude=-71.0589,\n address=\"1 Main St\",\n country=\"US\",\n )\n ```",
"properties": {
"status": {
"anyOf": [
{
"$ref": "#/$defs/Status"
},
{
"type": "null"
}
],
"default": null,
"description": "The status of the resource, optional."
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"name": {
"description": "The human-readable name of the location.",
"title": "Name",
"type": "string"
},
"albertId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The Albert ID of the location. Assigned by Albert and populated once the location has been created or retrieved.",
"title": "Albertid"
},
"latitude": {
"description": "The latitude of the location, in decimal degrees.",
"title": "Latitude",
"type": "number"
},
"longitude": {
"description": "The longitude of the location, in decimal degrees.",
"title": "Longitude",
"type": "number"
},
"address": {
"description": "The street address of the location.",
"title": "Address",
"type": "string"
},
"country": {
"anyOf": [
{
"maxLength": 2,
"minLength": 2,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The two-letter country code of the location (for example, ``\"US\"``).",
"title": "Country"
}
},
"required": [
"name",
"latitude",
"longitude",
"address"
],
"title": "Location",
"type": "object"
},
"ProjectClass": {
"description": "The access-control class of a project, governing who can see it.\n\n- ``PRIVATE``: visible only to the project's ACL members (the default).\n- ``SHARED``: visible more broadly across the organization.\n- ``CONFIDENTIAL``: restricted, most tightly controlled access.",
"enum": [
"shared",
"confidential",
"private"
],
"title": "ProjectClass",
"type": "string"
},
"State": {
"description": "The lifecycle state of a project.\n\nThe set of allowed states is customizable per tenant via the entity-status\nAPI; these are the platform defaults. Unknown tenant-specific values are\ntolerated as plain strings on [`Project.state`][albert.resources.projects.Project.state].",
"enum": [
"Not Started",
"Active",
"Closed - Success",
"Closed - Archived",
"Just Started",
"In Progress"
],
"title": "State",
"type": "string"
},
"Status": {
"description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n The resource is fully operational and visible in normal operations.\nINACTIVE : str\n The resource is hidden from normal operations and disabled from use.",
"enum": [
"active",
"inactive"
],
"title": "Status",
"type": "string"
},
"TaskConfig": {
"description": "Default task settings applied when tasks are created within a project.",
"properties": {
"datatemplateId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of the data template tasks default to.",
"title": "Datatemplateid"
},
"workflowId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of the workflow tasks default to.",
"title": "Workflowid"
},
"defaultTaskName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Default name applied to new tasks.",
"title": "Defaulttaskname"
},
"target": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Default target for the configured tasks.",
"title": "Target"
},
"hidden": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether this configuration is hidden in the UI.",
"title": "Hidden"
}
},
"title": "TaskConfig",
"type": "object"
}
},
"description": "A project in Albert: the top-level container for a piece of R&D work.\n\nA project groups the formulations designed for the work, its Worksheet (1:1\nwith the project), the Tasks run against it, and the inventory it references.\nCreate and manage projects through the\n[`ProjectCollection`][albert.collections.projects.ProjectCollection] (``client.projects``).\n\nOnly ``description`` is required to build one; it doubles as the project's\ndisplay name. The ``id`` and ``state`` are assigned by Albert and are read\nonly from the client's perspective.\n\n!!! example\n ```python\n from albert import Albert\n from albert.resources.projects import Project, ProjectClass\n client = Albert()\n project = client.projects.create(\n project=Project(\n description=\"Weatherproof Coatings 2026\",\n project_class=ProjectClass.SHARED,\n )\n )\n project.id\n # 'PRO123'\n ```",
"properties": {
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Read-only status string returned by Albert.",
"title": "Status"
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"description": {
"description": "Human-readable project name/description (1-2000 characters). Also serves as the project's display name.",
"maxLength": 2000,
"minLength": 1,
"title": "Description",
"type": "string"
},
"Locations": {
"anyOf": [
{
"items": {
"anyOf": [
{
"$ref": "#/$defs/Location"
},
{
"$ref": "#/$defs/EntityLink"
}
]
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "The locations the project is associated with. Optional.",
"title": "Locations"
},
"class": {
"anyOf": [
{
"$ref": "#/$defs/ProjectClass"
},
{
"type": "null"
}
],
"default": "private",
"description": "Access-control class (private, shared, or confidential). Defaults to private."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional prefix used when naming entities within the project.",
"title": "Prefix"
},
"appEngg": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Inventory Ids to be added as application engineering",
"title": "Appengg"
},
"albertId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The Albert Project ID (format ``PRO...``). Assigned by Albert and present once the project has been created or retrieved.",
"title": "Albertid"
},
"ACL": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/ACL"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Access-control entries controlling who can access the project. Optional.",
"title": "Acl"
},
"old_api_params": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Read-only. Do not use.",
"title": "Old Api Params"
},
"task_config": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/TaskConfig"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Default task settings applied to tasks created within the project.",
"title": "Task Config"
},
"grid": {
"anyOf": [
{
"$ref": "#/$defs/GridDefault"
},
{
"type": "null"
}
],
"default": null,
"description": "The default grid view (Property Data or Worksheet) shown for the project."
},
"Metadata": {
"anyOf": [
{
"additionalProperties": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "string"
},
{
"$ref": "#/$defs/EntityLinkWithName"
},
{
"$ref": "#/$defs/EntityLink"
},
{
"items": {
"anyOf": [
{
"$ref": "#/$defs/EntityLinkWithName"
},
{
"$ref": "#/$defs/EntityLink"
}
]
},
"type": "array"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Custom field values. Allowed keys and values are defined via the Custom Fields API. Optional.",
"title": "Metadata"
},
"state": {
"anyOf": [
{
"$ref": "#/$defs/State"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The project's lifecycle state. Read only on create; can be changed via [`update`][albert.collections.projects.ProjectCollection.update]. Tenant-customized states outside [`State`][albert.resources.projects.State] parse as plain strings.",
"title": "State"
}
},
"required": [
"description"
],
"title": "Project",
"type": "object"
}
Fields:
-
created(AuditFields | None) -
updated(AuditFields | None) -
_session(AlbertSession | None) -
description(str) -
locations(list[SerializeAsEntityLink[Location]] | None) -
project_class(ProjectClass | None) -
prefix(str | None) -
application_engineering_inventory_ids(list[str] | None) -
id(ProjectId | None) -
acl(list[ACL] | None) -
old_api_params(dict | None) -
task_config(list[TaskConfig] | None) -
grid(GridDefault | None) -
metadata(dict[str, MetadataItem] | None) -
status(str | None) -
state(State | str | None)
Validators:
Source code in src/albert/core/shared/models/base.py
description: str
Human-readable project name/description (1-2000 characters). Also serves as the project's display name.
The locations the project is associated with. Optional.
project_class: ProjectClass | None = ProjectClass.PRIVATE
Access-control class (private, shared, or confidential). Defaults to private.
Inventory Ids to be added as application engineering
id: ProjectId | None = None
The Albert Project ID (format PRO...). Assigned by Albert and present once the project has been created or retrieved.
task_config: list[TaskConfig] | None
Default task settings applied to tasks created within the project.
grid: GridDefault | None = None
The default grid view (Property Data or Worksheet) shown for the project.
Custom field values. Allowed keys and values are defined via the Custom Fields API. Optional.
Return the project-bound Smart Projects interface for this project.
Use this property for Smart Projects workflows: adding targets and
building smart datasets scoped to the project. For standalone target or
smart dataset creation, use
TargetCollection or
SmartDatasetCollection
instead.
Returns:
| Type | Description |
|---|---|
SmartProject or None
|
The [ |
Somehow, some statuses are capitalized in the API response. This ensures they are always lowercase.
Source code in src/albert/resources/projects.py
Bases: BaseAlbertModel, HydrationMixin[Project]
A lightweight (partial) project returned by project search.
Returned by search,
this carries only summary fields for fast listing. Use its hydration support
(or fetch by id via
get_by_id) to obtain
the full Project.
Show JSON schema:
{
"$defs": {
"EntityLinkWithName": {
"description": "EntityLink that includes the name field in serialization.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category"
}
},
"required": [
"id"
],
"title": "EntityLinkWithName",
"type": "object"
}
},
"description": "A lightweight (partial) project returned by project search.\n\nReturned by [`search`][albert.collections.projects.ProjectCollection.search],\nthis carries only summary fields for fast listing. Use its hydration support\n(or fetch by ``id`` via\n[`get_by_id`][albert.collections.projects.ProjectCollection.get_by_id]) to obtain\nthe full [`Project`][albert.resources.projects.Project].",
"properties": {
"albertId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The Albert Project ID (format ``PRO...``).",
"title": "Albertid"
},
"description": {
"description": "The project's name/description.",
"maxLength": 2000,
"minLength": 1,
"title": "Description",
"type": "string"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Read-only status string returned by Albert.",
"title": "Status"
},
"application": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/EntityLinkWithName"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Application tags associated with the project.",
"title": "Application"
},
"technology": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/EntityLinkWithName"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Technology tags associated with the project.",
"title": "Technology"
}
},
"required": [
"description"
],
"title": "ProjectSearchItem",
"type": "object"
}
Fields:
-
id(ProjectId | None) -
description(str) -
status(str | None) -
application(list[EntityLinkWithName] | None) -
technology(list[EntityLinkWithName] | None)
application: list[EntityLinkWithName] | None = None
Application tags associated with the project.
technology: list[EntityLinkWithName] | None = None
Technology tags associated with the project.
Bases: BaseAlbertModel
A document (attachment) search result linked to a project.
Returned by
document_search. Each
item describes an attachment's metadata rather than its file contents.
Show JSON schema:
{
"description": "A document (attachment) search result linked to a project.\n\nReturned by\n[`document_search`][albert.collections.projects.ProjectCollection.document_search]. Each\nitem describes an attachment's metadata rather than its file contents.",
"properties": {
"albertId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The Albert Attachment ID (format ``ATT...``).",
"title": "Albertid"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The document's file name.",
"title": "Name"
},
"mimeType": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The document's MIME type (e.g. ``application/pdf``).",
"title": "Mimetype"
},
"fileSize": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "The document's size in bytes.",
"title": "Filesize"
},
"projectId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of the project the document is linked to.",
"title": "Projectid"
},
"key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Storage key for the document.",
"title": "Key"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source system or origin of the document.",
"title": "Source"
},
"createdBy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of the user who uploaded the document.",
"title": "Createdby"
},
"createdByName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of the user who uploaded the document.",
"title": "Createdbyname"
},
"createdAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when the document was created.",
"title": "Createdat"
}
},
"title": "DocumentSearchItem",
"type": "object"
}
Fields:
-
id(AttachmentId | None) -
name(str | None) -
mime_type(str | None) -
file_size(int | None) -
project_id(str | None) -
key(str | None) -
source(str | None) -
created_by(str | None) -
created_by_name(str | None) -
created_at(str | None)